Códigos de error y solución de problemas

Causas y soluciones cuando al llamar a 1折AI encuentras 401, 404, 429, 529, 5xx, tiempos de espera y errores de Claude Code.

Primero revisa la siguiente lista en orden; la mayoría de los problemas se encuentran en los tres primeros pasos.

Orden de verificación

Dirección: las herramientas de Anthropic usan https://1zheai.com, las de OpenAI usan https://1zheai.com/v1. Ver Base URL y autenticación.
Clave API (API key): ¿está completa (sin espacios ni saltos de línea extra), ¿ha sido eliminada, ¿se introdujo en el campo correcto?
Saldo: ¿el saldo en la consola es suficiente?
ID del modelo: ¿coincide exactamente con el de modelos admitidos?
Red: desactiva el proxy y vuelve a probar en conexión directa.
Si aún no funciona: envíanos una reproducción mínima con curl (ver abajo), junto con la respuesta y el tiempo.

1
curl -i https://1zheai.com/v1/messages \
2
  -H "x-api-key: sk-你的Key" \
3
  -H "anthropic-version: 2023-06-01" \
4
  -H "content-type: application/json" \
5
  -d '{"model":"claude-sonnet-5-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

-i imprimirá el código de estado junto con las cabeceras de respuesta, lo cual es muy útil al depurar.

Referencia rápida de códigos de error

Código de estado	Causa común	Qué hacer
400	Problema en el cuerpo de la solicitud: nombre de parámetro incorrecto, tipo de campo incorrecto, `max_tokens` supera el límite del modelo, incluye campos beta que el upstream no reconoce	Revisa el campo señalado en `message`; para Claude Code consulta más abajo “Extra inputs are not permitted”
401	Clave API inválida, eliminada, deshabilitada, expirada, cuota propia agotada, o no incluida / colocada en la cabecera incorrecta	Todas las respuestas son `Invalid token`, revisa punto por punto; en Anthropic nativo usa `x-api-key` o `Authorization: Bearer`
403	Saldo de la cuenta insuficiente (`billing_error` / `insufficient_quota`); esta clave API no tiene habilitado ese modelo; la IP de la solicitud no está en la lista blanca de esta clave API (ambos son `permission_error`)	Recarga saldo, o edita las restricciones de modelo y la lista blanca de IP de esta clave API en la página “Clave API”
404	Ruta incorrecta, o el modelo no existe / no está disponible actualmente	`Invalid URL` verifica la dirección; `not_found_error` / `model_not_found` verifica el ID del modelo y la lista de disponibilidad
413	Cuerpo de la solicitud demasiado grande	Reduce el contenido enviado de una vez; divide los archivos grandes en partes
429	Limitación temporal de tasa por el upstream. Actualmente no aplicamos límites de velocidad a las claves API	Reintenta más tarde; en tareas por lotes añade retroceso exponencial
503	El modelo existe pero no hay un servicio upstream saludable disponible temporalmente, o fallo temporal del servicio	Reintenta más tarde; si el fallo persiste, contacta soporte indicando el ID de solicitud
500 / 502	Fallo temporal de la puerta de enlace o del upstream	Reintenta más tarde; si persiste, envía un correo a [email protected]
504	Tiempo de espera agotado en la solicitud	Usa streaming para salidas largas; aumenta el tiempo de espera del cliente
529	Sobrecarga del upstream Anthropic (`overloaded_error`)	Espera unos segundos y reintenta, o cambia temporalmente a otro modelo

El significado completo de los tipos de error oficiales de Anthropic (invalid_request_error, authentication_error, rate_limit_error, overloaded_error, etc.) está en la documentación oficial Errors.

Los errores devueltos por el upstream se devuelven con el código de estado y message tal cual, y message añade al final el request id de esta solicitud. Al usar /v1/messages, la capa externa es la estructura oficial {"type":"error","error":{...}}, y error.type se rellena con el tipo oficial según el código de estado; al usar /v1/chat/completions es la estructura {"error":{...}} de OpenAI.

Respuestas reales probadas

A continuación se muestran respuestas reales probadas el 2026-10-15 contra /v1/messages. Al usar /v1/chat/completions el contenido es el mismo, la capa externa no tiene "type":"error", y error tiene un campo code adicional.

{"error":{"message":"Invalid token (request id: 202610150244355244812608268d9d6T1pY7T84)","type":"authentication_error"},"type":"error"}

{"error":{"type":"billing_error","message":"Insufficient user quota, remaining quota: ＄0.000000 (request id: 202610150244418753787808268d9d67YNhvwXd)"},"type":"error"}

{"error":{"message":"This token has no access to model claude-sonnet-4-6 (request id: 202610150244377127013108268d9d6yCiFOxJA)","type":"permission_error"},"type":"error"}

{"error":{"message":"Your IP address is not on this token's allowlist (request id: 202610150244409011371208268d9d63tJvd5GD)","type":"permission_error"},"type":"error"}

{"error":{"type":"invalid_request_error","message":"messages: Unexpected role \"robot\". Allowed roles are \"user\", \"assistant\" or \"system\" (request id: 202610150245008404167198268d9d6sajV9TX3)"},"type":"error"}

{"error":{"message":"Invalid URL (POST /v1/nonexistent)","type":"invalid_request_error","param":"","code":""}}

La explicación del 404 cuando el modelo no existe o no está disponible está en modelos admitidos. El request id de la respuesta corresponde a tu solicitud; inclúyelo al reportar un problema.

Verificación por síntoma

401 / Invalid token

La clave API se copió con espacios o saltos de línea extra; vuelve a copiarla.
La clave API fue eliminada o deshabilitada en la consola, o expiró, o su cuota propia se agotó. En todos estos casos la respuesta es la misma frase Invalid token.
En Claude Code se han configurado a la vez ANTHROPIC_API_KEY y ANTHROPIC_AUTH_TOKEN, y uno de ellos es un valor antiguo: deja solo uno, se recomienda ANTHROPIC_AUTH_TOKEN.
El env de settings.json sobrescribe la variable homónima exportada en la terminal; si cambiar la variable de la terminal no surte efecto, revisa ~/.claude/settings.json.

404 / Invalid URL

Primero mira el tipo de error: not_found_error o model_not_found requieren revisar el ID del modelo y la lista de disponibilidad. Invalid URL requiere revisar /v1: OpenAI SDK, Cursor, Cline (OpenAI Compatible) deben rellenar hasta https://1zheai.com/v1; Claude Code y el SDK de Anthropic solo rellenan https://1zheai.com, si rellenas /v1 se convertirá en /v1/v1/messages.

403 / error code: 1010

Si la respuesta solo contiene la línea error code: 1010 y no hay JSON, significa que la solicitud fue bloqueada antes de llegar a la puerta de enlace. Se sabe que ocurre al enviar solicitudes directamente con la biblioteca estándar de Python urllib (su User-Agent por defecto es Python-urllib/3.x). Añade tu propio User-Agent en las cabeceras de la solicitud, o cambia al SDK oficial, requests, httpx.

429 demasiadas solicitudes

Actualmente no aplicamos límites de velocidad a las claves API. Recibir un 429 suele deberse a alta carga en el upstream; reintenta más tarde. Para tareas por lotes se recomienda retroceso exponencial: espera un tiempo tras cada fallo antes de reintentar, duplicando la espera en cada intento, y controla la concurrencia con tu propia cola.

529 / overloaded_error

El upstream Anthropic está sobrecargado temporalmente; no tiene relación con tu clave API ni con tu saldo. Espera unos segundos y reintenta; si tienes prisa, cambia temporalmente a otro modelo de la misma serie.

Tiempos de espera, desconexión a mitad del streaming

Para respuestas largas usa streaming ("stream": true) siempre que sea posible; es menos propenso a ser cortado por dispositivos de red intermedios.
Claude Code puede usar API_TIMEOUT_MS para aumentar el tiempo de espera; el valor por defecto es 600000 (10 minutos).
Si tienes un proxy activado, desactívalo y prueba una vez; muchas desconexiones de streaming provienen de nodos de proxy.

Claude Code: entra directamente en la interfaz de inicio de sesión

Significa que Claude Code no leyó tu clave API. Ejecuta /status en Claude Code y revisa las líneas de base URL y origen de credenciales; si están vacías, vuelve a integración con Claude Code para revisar las variables de entorno o settings.json.

Claude Code: Extra inputs are not permitted / context_management devuelve 400

Claude Code incluye en la solicitud algunos campos beta experimentales; un upstream estricto que no los reconoce devolverá 400. Configura la siguiente variable de entorno para desactivarlos (procedente de la documentación oficial de LLM gateway de Claude Code):

1
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

Saldo suficiente pero las llamadas fallan

Si solo falla un modelo, puede que ese modelo esté temporalmente no disponible, que el ID esté mal escrito, o que esta clave API tenga restricciones de modelo (403 This token has no access to model …).
Si todos fallan con 401, comprueba si esta clave API tiene un límite de cuota ya agotado, o si expiró. Puedes verlo en las columnas “Cuota ($)” y “Expira” de la página “Clave API”.
Para otros casos consulta la tabla de códigos de error anterior.

Reintentos limitados y plantilla de reporte

No uses bucles infinitos para ocultar errores de configuración. Para tiempos de espera del SDK, número de reintentos automáticos y manejo de retroceso consulta tiempos de espera y reintentos.

Al contactar con soporte puedes copiar la siguiente plantilla, eliminar las claves, cabeceras de autenticación y contenido privado antes de enviarla:

1
发生时间与时区：
2
客户端及版本：
3
请求方法与完整路径：
4
模型 ID：
5
HTTP 状态码：
6
request id（如有）：
7
脱敏后的错误正文：
8
最小请求能否复现：
9
是否使用代理 / 是否仅某个模型失败：

Aún no resuelto

Envía un correo a [email protected], adjuntando la hora, el ID del modelo, la herramienta y versión que usas, y la salida completa de curl -i (elimina la clave API).