--- title: "Códigos de error y solución de problemas" description: "Causas y soluciones cuando al llamar a 1折AI encuentras 401, 404, 429, 529, 5xx, tiempos de espera y errores de Claude Code." headingIds: {"Orden de verificación":"section-1","Referencia rápida de códigos de error":"section-2","Respuestas reales probadas":"section-3","Verificación por síntoma":"section-4","401 / Invalid token":"section-5","404 / Invalid URL":"section-6","403 / error code: 1010":"section-7","429 demasiadas solicitudes":"section-8","529 / overloaded_error":"section-9","Tiempos de espera, desconexión a mitad del streaming":"section-10","Claude Code: entra directamente en la interfaz de inicio de sesión":"section-11","Claude Code: Extra inputs are not permitted / context_management devuelve 400":"section-12","Saldo suficiente pero las llamadas fallan":"section-13","Reintentos limitados y plantilla de reporte":"section-14","Aún no resuelto":"section-15"} --- Primero revisa la siguiente lista en orden; la mayoría de los problemas se encuentran en los tres primeros pasos. ## Orden de verificación 1. **Dirección**: las herramientas de Anthropic usan `https://1zheai.com`, las de OpenAI usan `https://1zheai.com/v1`. Ver [Base URL y autenticación](/es/docs/base-url/). 2. **Clave API (API key)**: ¿está completa (sin espacios ni saltos de línea extra), ¿ha sido eliminada, ¿se introdujo en el campo correcto? 3. **Saldo**: ¿el saldo en la consola es suficiente? 4. **ID del modelo**: ¿coincide exactamente con el de [modelos admitidos](/es/docs/models/)? 5. **Red**: desactiva el proxy y vuelve a probar en conexión directa. 6. **Si aún no funciona**: envíanos una reproducción mínima con curl (ver abajo), junto con la respuesta y el tiempo. ```bash title="最小复现" curl -i https://1zheai.com/v1/messages \ -H "x-api-key: sk-你的Key" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -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 support@1zheai.com | | 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](https://platform.claude.com/docs/en/api/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. ```json title="401 API 密钥无效、禁用、过期或额度用完" {"error":{"message":"Invalid token (request id: 202610150244355244812608268d9d6T1pY7T84)","type":"authentication_error"},"type":"error"} ``` ```json title="403 账户余额不足" {"error":{"type":"billing_error","message":"Insufficient user quota, remaining quota: ＄0.000000 (request id: 202610150244418753787808268d9d67YNhvwXd)"},"type":"error"} ``` ```json title="403 API 密钥没开通该模型" {"error":{"message":"This token has no access to model claude-sonnet-4-6 (request id: 202610150244377127013108268d9d6yCiFOxJA)","type":"permission_error"},"type":"error"} ``` ```json title="403 IP 不在白名单" {"error":{"message":"Your IP address is not on this token's allowlist (request id: 202610150244409011371208268d9d63tJvd5GD)","type":"permission_error"},"type":"error"} ``` ```json title="400 上游参数错误" {"error":{"type":"invalid_request_error","message":"messages: Unexpected role \"robot\". Allowed roles are \"user\", \"assistant\" or \"system\" (request id: 202610150245008404167198268d9d6sajV9TX3)"},"type":"error"} ``` ```json title="404 路径不存在" {"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](/es/docs/models/). 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](/es/docs/models/). `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](/es/docs/quickstart-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): ```bash 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](/es/docs/retries/). Al contactar con soporte puedes copiar la siguiente plantilla, eliminar las claves, cabeceras de autenticación y contenido privado antes de enviarla: ```text 发生时间与时区： 客户端及版本： 请求方法与完整路径： 模型 ID： HTTP 状态码： request id（如有）： 脱敏后的错误正文： 最小请求能否复现： 是否使用代理 / 是否仅某个模型失败： ``` ## Aún no resuelto Envía un correo a support@1zheheai.com, 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).