Errores y límites de tasa
Formas de las respuestas de error, la tabla completa de códigos de estado HTTP, el comportamiento de los límites de tasa y una estrategia de reintentos que funciona con Atlas Cloud.
Formas de las respuestas de error
Atlas Cloud devuelve tres formas de error distintas según la parte de la API que llames. Comprueba la forma antes de escribir un parser.
La usan los endpoints de protocolo LLM y los endpoints de generación de medios:
{
"code": 401,
"msg": "unauthorized",
"request_id": "…",
"data": null
}Toda respuesta lleva un encabezado X-Request-ID. Regístralo — es la vía más rápida para que el soporte rastree una llamada concreta.
Códigos de estado HTTP
| Estado | Significado | Qué hacer |
|---|---|---|
400 | Solicitud mal formada: cuerpo no parseable, falta model, tipo de contenido incorrecto, encabezado de retención inválido o un webhook_url inválido | Corrige la solicitud. El campo msg indica el problema concreto |
401 | Fallo de autenticación — clave ausente, desconocida o caducada | Revisa la clave. Ten en cuenta que una ruta URL incorrecta también devuelve 401, así que verifica también el endpoint |
402 | Saldo insuficiente, o una asignación de Coding Plan agotada | Recarga |
403 | La cuenta o el usuario no tienen permiso — incluye usar una clave de Coding Plan en un modelo que no las acepta | Revisa el alcance de la clave o contacta con soporte |
404 | Recurso no encontrado. En los modelos, también cubre los que no están disponibles para tu cuenta | Comprueba el ID del modelo en el catálogo |
413 | El cuerpo de la solicitud supera los 50 MB | Envía una URL en lugar de Base64 en línea, o sube el archivo primero |
429 | Límite de tasa alcanzado | Aplica backoff y reintenta — ver abajo |
451 | Bloqueado en tu región | No reintentable |
500 | Error interno | Reintenta una vez y luego repórtalo con el ID de la solicitud |
503 | No disponible temporalmente | Reintenta con backoff |
504 | Una solicitud síncrona superó la espera máxima | Cambia al flujo asíncrono y consulta el estado |
Un 401 no siempre significa que tu clave sea incorrecta. La pasarela autentica antes de enrutar, así que una errata en la ruta también produce 401 en lugar de 404. Si una clave funciona en otro sitio, revisa primero la URL.
Códigos de error a nivel de tarea
Cuando una tarea asíncrona falla, data.error_code lleva un código numérico de plataforma más específico que el estado HTTP. Por ejemplo, 1039 indica que la entrada fue rechazada por la moderación de contenido.
data.error contiene una descripción legible. Registra ambos, junto con el ID de la predicción.
Límites de tasa
Los límites de tasa se aplican por cuenta y por modelo. Superar uno devuelve 429.
Los endpoints de LLM y de medios no devuelven X-RateLimit-Limit, X-RateLimit-Remaining ni Retry-After. No puedes leer tu cuota restante desde los encabezados de respuesta — implementa el backoff en el cliente.
Los endpoints de facturación /public/v1 son la excepción: sus respuestas 429 sí incluyen Retry-After.
Si necesitas límites más altos para una carga de trabajo en producción, contáctanos indicando el volumen de solicitudes previsto y la combinación de modelos.
Estrategia de reintentos
Reintenta en 429, 500, 503 y 504, además de en los fallos a nivel de red. No reintentes 400, 401, 402, 403, 404 ni 451 — fallarán igual.
Reintenta las solicitudes de lectura sin problema. Ten cuidado al reintentar envíos de generación: una solicitud que agotó el tiempo de espera puede haberse aceptado igualmente, y un reintento a ciegas puede crear — y facturar — una segunda tarea. Es preferible enviar de forma asíncrona y consultar el estado, para que una respuesta perdida nunca signifique una tarea perdida.
import time, random, requests
RETRYABLE = {429, 500, 503, 504}
def call_with_retry(url, payload, api_key, max_attempts=4):
for attempt in range(max_attempts):
response = requests.post(
url,
json=payload,
headers={"Authorization": f"Bearer {api_key}"},
timeout=60,
)
if response.status_code not in RETRYABLE:
return response
if attempt == max_attempts - 1:
break
# Backoff exponencial + jitter, para que muchos clientes no reintenten a la vez
delay = min(2 ** attempt, 30) * (0.5 + random.random() / 2)
time.sleep(delay)
return responseErrores en streaming
Cuando una solicitud en streaming falla antes de que se abra el stream, recibes un error HTTP normal. Una vez iniciado el stream, la conexión permanece abierta y el error llega como un evento dentro del stream — así que un 200 en una llamada en streaming no garantiza una respuesta completa. Gestiona siempre la terminación a mitad del stream.
Los streams también pueden contener líneas de comentario SSE que empiezan por : como señales de keep-alive. No son datos y deben ignorarse — la mayoría de los clientes SSE lo hacen por ti, pero los parsers hechos a mano a menudo no.
Cómo obtener ayuda
Al informar de un problema, incluye:
- El encabezado
X-Request-IDde la respuesta que falló - El ID de la predicción, en el caso de tareas asíncronas
- El ID exacto del modelo y la marca de tiempo
Contáctanos a través de Soporte.
Relacionado
Last updated on