Errores de la API de Claude: 400, 401, 429, 529 y soluciones

Respuesta corta

La API de Claude informa de cada fallo con un JSON que lleva un estado HTTP y un error.type: 400 invalid_request_error (algo falla en el cuerpo de la solicitud), 401 authentication_error (clave ausente o incorrecta), 403 permission_error, 404 not_found_error (ruta o ID de modelo incorrectos), 413 request_too_large, 429 rate_limit_error, 500 api_error y 529 overloaded_error. Los errores 4xx se corrigen cambiando la solicitud, porque reenviarla sin cambios vuelve a fallar; los 429, 500, 503 y 529 se reintentan con espera exponencial (backoff), respetando la cabecera retry-after cuando aparece. En APIVAI se aplican los mismos códigos, más 402 insufficient_quota cuando se agota el presupuesto de una clave, y el límite por defecto es de 60 solicitudes por minuto por clave. La mayoría de los 404 se deben a la URL base: usa https://api.apivai.com para el formato de Anthropic y https://api.apivai.com/v1 para el formato de OpenAI.

¿Cómo es una respuesta de error de la API de Claude?

La API de Anthropic devuelve los errores en JSON con un objeto error de primer nivel que siempre tiene type y message, como explica la página oficial de errores de la API de Claude. APIVAI responde con la misma forma:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Not found. Check the model name and the endpoint path."
  }
}

El formato de OpenAI (POST /v1/chat/completions y /v1/responses) usa tradicionalmente {"error": {"message": "...", "type": "...", "param": null, "code": "..."}}. En APIVAI, los errores de estos endpoints usan el mismo cuerpo de arriba. Los SDK y las herramientas de OpenAI leen error.message y error.type, que siempre están presentes; en los errores 400, 404 y 413 el cuerpo también puede incluir code y param cuando indican qué campo falló.

Lee siempre primero error.message. En los problemas de la solicitud (400, 404, 413) suele nombrar el campo o el modelo exacto que causó el error.

¿Qué significan los códigos de error de la API de Claude?

HTTP	error.type	Qué significa	Qué hacer	¿Reintentar?
400	`invalid_request_error`	Cuerpo o parámetros incorrectos	Corregir el campo indicado en el mensaje	No
401	`authentication_error`	Clave ausente o no válida	Revisar la clave y la cabecera	No
402	`insufficient_quota`	Presupuesto de la clave agotado (APIVAI)	Añadir presupuesto a la clave en el Dashboard	No
403	`permission_error`	Cuenta desactivada o recurso no permitido	Contactar con soporte	No
404	`not_found_error`	Ruta, URL base o ID de modelo incorrectos	Revisar `/v1` y el ID del modelo	No
413	`request_too_large`	Cuerpo de la solicitud demasiado grande	Enviar menos datos	No
429	`rate_limit_error`	Demasiadas solicitudes por minuto o presupuesto de la clave agotado	Esperar; leer el mensaje	Sí, con backoff
500	`api_error`	Error inesperado del servidor	Reintentar con backoff	Sí
503 / 529	`overloaded_error`	Sobrecarga temporal	Reintentar con backoff	Sí

La lista oficial de Anthropic también incluye 402 billing_error (un problema de pago en una cuenta de Anthropic), 409 conflict_error y 504 timeout_error. Para generaciones largas, la recomendación oficial contra los tiempos de espera es usar streaming. En APIVAI, el 402 siempre significa que se agotó el presupuesto de la clave que estás usando.

¿Por qué recibo 401 «invalid x-api-key» o «Invalid API key»?

Un 401 authentication_error significa que la solicitud llegó a la API pero la clave no fue aceptada. APIVAI devuelve «Missing API key.» cuando no se envió ninguna clave e «Invalid API key.» cuando la clave no es tuya.

Revisa en este orden:

La cabecera. El formato de Anthropic suele enviar x-api-key: <key> y el de OpenAI Authorization: Bearer <key>. APIVAI acepta cualquiera de las dos en ambos formatos, así que aquí un 401 tiene que ver con la clave en sí, no con la cabecera elegida.
El texto de la clave. Cópiala de nuevo desde el Dashboard; es habitual que falte un carácter o que se peguen espacios o comillas.
Se está enviando otra clave. Una variable de entorno antigua ANTHROPIC_API_KEY u OPENAI_API_KEY puede imponerse sobre la clave que escribiste en los ajustes de la herramienta. La guía de configuración de Claude Code explica qué variables lee Claude Code.
La clave se borró o se regeneró. Una clave regenerada sustituye a la anterior; actualízala en todas las herramientas que la usaban.

Un 403 permission_error con «This account is disabled. Contact support.» significa que la clave es válida pero la cuenta está desactivada; cambiar de clave no sirve, así que escribe a soporte.

¿Cómo soluciono 429 rate_limit_error y 402 insufficient_quota?

En APIVAI, cada clave tiene dos límites:

Una frecuencia de solicitudes. Por defecto son 60 solicitudes por minuto por clave. Los agentes que lanzan muchas llamadas en paralelo pueden superarla. Reduce la concurrencia, reintenta con backoff o pide a soporte que suba el límite.
Un presupuesto. Cada clave tiene su propio presupuesto, que se toma del saldo de la cuenta al crear la clave o al añadirle presupuesto. Cuando se agota, las solicitudes fallan con 402 insufficient_quota («This key has no budget left. Add budget to the key in the dashboard.») o con un 429 cuyo mensaje dice que el presupuesto de la clave se ha agotado.

Los errores de presupuesto no desaparecen al reintentar. Abre el Dashboard y añade presupuesto a esa clave. Si el saldo de la cuenta también está vacío, recarga primero (desde $10). Tu saldo puede tener dinero mientras una clave concreta no tiene: para sus solicitudes cuenta el presupuesto propio de la clave. Los precios actuales por token están en la página de precios.

¿Qué es overloaded_error (529) y cómo debo reintentar?

overloaded_error significa que el servicio está sobrecargado temporalmente. No lo causa tu solicitud, y la misma solicitud suele funcionar poco después. APIVAI lo devuelve como 529, o como 503 con el mismo tipo overloaded_error. El 500 api_error se trata igual.

El patrón correcto es la espera exponencial: espera alrededor de 1 s, luego 2 s, 4 s, 8 s, añade algo de variación aleatoria (jitter) y para tras unos cuantos intentos. Si la respuesta trae la cabecera retry-after, espera al menos ese tiempo; APIVAI transmite retry-after y retry-after-ms cuando vienen definidas.

Los SDK oficiales de Anthropic ya lo hacen: por defecto reintentan dos veces los errores de conexión, los 429 y las respuestas 5xx con espera exponencial y respetan retry-after. Solo tienes que subir max_retries:

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.apivai.com",
    api_key="YOUR_APIVAI_KEY",
    max_retries=5,  # default is 2
)

try:
    msg = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=4096,
        messages=[{"role": "user", "content": "Hello"}],
    )
    print("".join(b.text for b in msg.content if b.type == "text"))
except anthropic.APIStatusError as e:
    print(e.status_code, e.response.headers.get("request-id"), e.message)

Sin SDK basta con un bucle pequeño. Solo reintenta los códigos temporales y se detiene cuando un 429 se refiere al presupuesto:

import random, time, requests

RETRY = {429, 500, 503, 529}

def post_with_backoff(url, headers, body, attempts=5):
    for i in range(attempts):
        r = requests.post(url, headers=headers, json=body, timeout=600)
        if r.status_code not in RETRY or "budget" in r.text:
            return r
        wait = float(r.headers.get("retry-after", 2 ** i))
        time.sleep(wait + random.random())
    return r

¿Por qué recibo 404 not_found_error?

Casi siempre es la URL base o el ID del modelo:

Formato de Anthropic: URL base https://api.apivai.com, sin /v1. El SDK de Anthropic y Claude Code añaden /v1/messages por su cuenta, así que https://api.apivai.com/v1 se convierte en /v1/v1/messages y falla.
Formato de OpenAI: URL base https://api.apivai.com/v1, con un solo /v1. Sin él, la solicitud va a /chat/completions y APIVAI responde «Unknown endpoint».
Host equivocado: las solicitudes enviadas a apivai.com en lugar de api.apivai.com reciben un 404 cuyo mensaje dice «Wrong base URL» e indica las dos direcciones correctas.
ID del modelo: usa un ID exacto como claude-sonnet-4-6, no un nombre comercial. Lista los ID que puede usar tu clave:

curl https://api.apivai.com/v1/models \
  -H "Authorization: Bearer YOUR_APIVAI_KEY"

Los modelos Claude funcionan en ambos formatos; los modelos GPT como gpt-5.5, solo en el formato de OpenAI. Más sobre cada formato: proxy de la API de Claude y API compatible con OpenAI.

¿Por qué ocurre un 400 invalid_request_error?

Un 400 significa que la API entendió la solicitud pero rechazó su contenido. El mensaje indica el problema. Los más frecuentes:

Falta max_tokens en una solicitud con formato de Anthropic (allí es obligatorio).
La conversación termina con un mensaje del asistente (prefill). Los modelos Claude 4.6 y posteriores lo rechazan; termina con un mensaje del usuario.
Un ajuste de thinking antiguo: los modelos más nuevos, como claude-opus-5-5, rechazan thinking: {"type": "enabled"} y esperan adaptive thinking. Quita el campo thinking para usar el valor por defecto.
Bloques de thinking editados o eliminados antes de reenviarlos en un bucle con herramientas. Devuélvelos exactamente como llegaron.

Un problema relacionado no es un error en absoluto: respuestas vacías o cortadas. El thinking está activado por defecto y sus tokens cuentan como salida, así que un max_tokens pequeño puede agotarse antes de que aparezca texto. La respuesta termina con stop_reason: "max_tokens" (o finish_reason: "length" en el formato de OpenAI). Sube max_tokens a 4096 o más.

413 request_too_large significa que el propio cuerpo es demasiado grande. El límite de Anthropic para la Messages API es de 32 MB. Las causas habituales son archivos grandes en base64 e historiales muy largos: envía menos archivos o más pequeños, o recorta los turnos antiguos.

¿Cómo aparecen los errores en una respuesta en streaming?

Con "stream": true, el estado HTTP es 200 en cuanto empieza el flujo, así que un fallo posterior ya no puede cambiarlo. En su lugar llega como un evento dentro del flujo. La documentación de streaming de Anthropic da este ejemplo:

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

Si un flujo a través de APIVAI se corta antes de completarse, APIVAI envía un event: error con api_error y «The response was interrupted. Please retry.» en lugar de terminar en silencio, de modo que los SDK lanzan una excepción en vez de devolver media respuesta. Trátalo como un 500: reintenta la solicitud completa.

¿Cómo encuentro el request ID?

Las respuestas pueden llevar una cabecera request-id (algunos servicios usan x-request-id); APIVAI la transmite siempre que existe. Muestra las cabeceras con curl:

curl -sS -D - https://api.apivai.com/v1/messages \
  -H "x-api-key: YOUR_APIVAI_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hi"}]}'

En el SDK de Python, una respuesta correcta tiene msg._request_id y una excepción tiene e.response.headers. Incluye el ID, la hora y el mensaje de error cuando contactes con soporte.

¿Cuáles son las causas más comunes, de un vistazo?

Síntoma	Causa probable	Solución
404 en todas las solicitudes	`/v1` ausente, de más o duplicado	Anthropic: `https://api.apivai.com`; OpenAI: `https://api.apivai.com/v1`
401 con una clave que parece correcta	Una variable de entorno antigua envía otra clave	Eliminarla o sustituirla por la clave de APIVAI
404 o 400 que nombra el modelo	Errata o nombre comercial	Copiar el ID de `GET /v1/models`
Respuestas vacías o cortadas	`max_tokens` demasiado bajo con thinking	4096 o más
413	Archivos grandes en el cuerpo	Enviar menos datos
429 durante ejecuciones de agentes	Más de 60 solicitudes por minuto	Bajar la concurrencia, backoff
402, o 429 sobre presupuesto	Presupuesto de la clave agotado	Añadir presupuesto a la clave
529 / 503	Sobrecarga temporal	Reintentar con backoff

Las configuraciones de cada herramienta están en la documentación y en guías como Cline con Claude y GPT.

Preguntas frecuentes

¿Debo reintentar un error 400 o 401?

No. Los errores 4xx distintos de 429 describen un problema en la solicitud o en la clave, y la misma solicitud falla igual. Corrige primero la causa.

¿Qué diferencia hay entre 429 y 529?

El 429 tiene que ver con tus propios límites: solicitudes por minuto y, en APIVAI, también el presupuesto de la clave. El 529 overloaded_error es una sobrecarga temporal que no depende de tu uso; tanto los 429 por frecuencia como los 529 se reintentan con backoff.

¿El SDK de Anthropic reintenta automáticamente?

Sí. Por defecto reintenta dos veces los errores de conexión, los 429 y las respuestas 5xx con espera exponencial y respeta retry-after. Ajusta max_retries en el cliente para cambiarlo, o ponlo a 0 para desactivarlo.

¿Por qué la respuesta llega vacía sin ningún error?

El thinking consumió todo el max_tokens antes del texto visible. Sube max_tokens a 4096 o más; los tokens de thinking se cobran como tokens de salida.

Mi cuenta tiene saldo, ¿por qué recibo un 402?

El saldo y el presupuesto de la clave son cosas distintas. Cada clave gasta solo su propio presupuesto; añade presupuesto a esa clave en el Dashboard.

Crea una cuenta, recarga desde $10 y crea una clave para llamar a Claude y GPT con una sola API.