Errores
Todos los códigos de estado que devuelve la pasarela, sus causas reales y cómo solucionarlos.
Los errores devuelven JSON con un type y un mensaje legible para las personas message. Los códigos de estado siguen las convenciones de Anthropic y OpenAI.
{"type": "error", "error": {"type": "authentication_error", "message": "invalid api key"}}Códigos de estado
| Código | Significado | Causa real más común | Solución |
|---|---|---|---|
400 | Solicitud incorrecta | Falta max_tokens en Messages, o hay un elemento mal formado: messages matriz | Comprueba el cuerpo con Messages |
401 | Sin autenticar | Clave enviada en el encabezado incorrecto para el formato | x-api-key para Messages, Bearer para Chat Completions |
402 | Pago requerido | Saldo agotado o plan caducado | Recargar saldo o comprar un plan |
403 | Acceso prohibido | Clave revocada o modelo no habilitado para la cuenta | Crea una nueva clave; comprueba /v1/models |
404 | No encontrado | Error en la URL base: normalmente se ha duplicado u omitido /v1 | Consulta URL base |
429 | Límite de solicitudes alcanzado | Demasiadas solicitudes simultáneas | Aumenta exponencialmente la espera entre reintentos; consulta Límites de solicitudes |
500 | Error de la puerta de enlace | Fallo interno inesperado | Reintenta una vez; si persiste, contacta con soporte e indica el identificador de la solicitud |
529 | Proveedor sobrecargado | Capacidad del proveedor, no de tu cuenta | Reintenta aumentando la espera; suele resolverse en segundos |
Tipos de error
| tipo | Significado |
|---|---|
invalid_request_error | El cuerpo está mal formado o falta un campo obligatorio |
authentication_error | La clave falta, está mal formada o ha sido revocada |
permission_error | La clave es válida, pero no tiene permiso para usar ese modelo |
not_found_error | Ruta o identificador de modelo desconocido |
rate_limit_error | Solicitudes limitadas |
api_error | Fallo interno |
overloaded_error | Capacidad del proveedor agotada |
Cómo reintentar correctamente
Reintento 429, 500, 502, 503 y 529. Nunca reintentes a ciegas 400, 401, 402 o 403 : la misma solicitud falla de la misma manera y, si la respuesta se ha generado parcialmente, puedes pagar dos veces.
import time, httpx
def call(body, key, tries=4):
for i in range(tries):
r = httpx.post(class="s">"https://aiprimetech.io/v1/messages", json=body, timeout=120,
headers={class="s">"x-api-key": key,
class="s">"anthropic-version": class="s">"2023-06-01"})
if r.status_code in (429, 500, 502, 503, 529):
time.sleep(2 ** i) class=class="s">"c"># 1s, 2s, 4s, 8s
continue
r.raise_for_status()
return r.json()
raise RuntimeError(class="s">"upstream unavailable after retries")Añade una variación aleatoria al tiempo de espera en producción. Los reintentos sincronizados de muchos procesos de trabajo convierten un fallo puntual en una avalancha de solicitudes contra el mismo proveedor.