Volver al blog

Solución de problemasGuía

Errores de conexión comunes y cómo solucionarlos

Qué significan 401, 402, 400, 404, 413, 429 y 503 cuando te conectas a la API de CheapTokens, cómo son las respuestas y cómo solucionar cada uno.

Por CheapTokens TeamPublicado el 3 min de lectura

Lista de códigos de estado HTTP 401, 402, 400, 404 y 429 con breves explicaciones en una terminal
En esta página
  1. Comprobación rápida
  2. 401 — Clave de API no válida
  3. 402 — saldo vacío o sin clave en la petición
  4. 404 — dirección incorrecta
  5. 400 — modelo no encontrado
  6. 413 — petición demasiado grande
  7. 429 — demasiadas peticiones
  8. 503 — modelo temporalmente no disponible
  9. Esperas largas y timeouts

Casi todos los problemas de conexión se reducen a cuatro cosas: la dirección, la clave, el ID del modelo y el saldo. Empieza con la comprobación rápida de abajo y luego busca tu código de estado. Los cuerpos de respuesta citados aquí son las respuestas reales de la API (octubre de 2026).

Comprobación rápida#

bash
# 1. The address is reachable — this request needs no key
curl https://api.cheaptokens.dev/v1/models

# 2. The key and the balance work — a tiny request (costs a fraction of a cent)
curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-ai/DeepSeek-V4-Flash-0731", "max_tokens": 5,
       "messages": [{"role": "user", "content": "ping"}]}'

Si el primer comando falla, la causa puede ser la red de tu lado, un error tipográfico en la dirección — o que el propio servicio esté temporalmente no disponible. Si solo falla el segundo, busca su código de estado abajo. Si ambos funcionan pero tu herramienta no, compara la configuración de la herramienta con estos dos comandos.

401 — Clave de API no válida#

json
{"error": {"message": "Invalid API key", "type": "authentication_error"}}

Los clientes de estilo Anthropic reciben el mismo error en su formato:

json
{"type": "error", "error": {"type": "authentication_error", "message": "Invalid API key"}}

Causas:

  • la clave se copió con un carácter faltante, un espacio o comillas;
  • la clave se rotó en el panel — la antigua ya no funciona;
  • se configuró una clave de otro servicio (por ejemplo OpenAI) en lugar de la clave de CheapTokens;
  • la variable de entorno está vacía en esta terminal: echo ${#CHEAPTOKENS_API_KEY} imprime su longitud.

El panel muestra una clave solo una vez. Si se pierde, pulsa Rotate para obtener una nueva y actualízala en todos los lugares donde se use.

402 — saldo vacío o sin clave en la petición#

La API devuelve 402 en dos situaciones diferentes:

  1. El saldo se ha agotado. Las peticiones se pagan con el saldo; cuando se acaba, la clave se pausa. Recarga en el panel y las peticiones vuelven a pasar.
  2. La petición no tiene ninguna clave. Si falta la cabecera Authorization (o x-api-key para clientes de estilo Anthropic), la API responde 402 con el tipo insufficient_funds. Comprueba que tu herramienta realmente envía la clave: el estilo OpenAI es Authorization: Bearer <key>.

404 — dirección incorrecta#

json
{"error": {"message": "Invalid URL (GET /v1/chat/completion)", "type": "invalid_request_error", "param": null, "code": null}}

La ruta tiene un error tipográfico — aquí completion en lugar de completions. Otras causas comunes:

  • La URL base no tiene /v1. Los clientes de estilo OpenAI necesitan https://api.cheaptokens.dev/v1. Sin /v1 la petición no llega a la API y obtienes una página HTML 404 normal en lugar de JSON.
  • /v1 dos veces. Algunos clientes añaden /v1 por su cuenta; entonces la URL base debe ser la raíz, https://api.cheaptokens.dev. Los clientes de estilo Anthropic siempre usan la dirección raíz.

400 — modelo no encontrado#

json
{"error": {"message": "Model \"deepseek-v4-flash\" not found. Available: …", "type": "invalid_request_error", "param": "model"}}

El ID del modelo debe ser el ID completo, incluido el prefijo antes de la barra: deepseek-ai/DeepSeek-V4-Flash-0731, no deepseek-v4-flash. Da igual mayúsculas o minúsculas. El mensaje de error lista los ID disponibles, y la lista completa está siempre en GET /v1/models.

Un 400 también se devuelve por un cuerpo de petición mal formado — por ejemplo un array messages vacío (messages field is required and must be a non-empty array) o un mensaje sin role.

413 — petición demasiado grande#

El cuerpo de la petición está limitado a 16 MB. Los agentes pueden alcanzarlo al meter archivos o logs enormes en el contexto. Envía solo las partes que el modelo necesita y recorta la salida larga de las herramientas.

429 — demasiadas peticiones#

Si recibes 429, baja el ritmo. La respuesta incluye una cabecera Retry-After con el número de segundos a esperar. Los SDK oficiales de OpenAI reintentan automáticamente (max_retries); en tu propio código, espera Retry-After antes del siguiente intento.

503 — modelo temporalmente no disponible#

Un modelo puede estar temporalmente no disponible; la API entonces responde 503 con el tipo model_unavailable, y la ficha del modelo en el sitio muestra "temporalmente no disponible". Reintenta más tarde o cambia el campo model a otro modelo — la clave y la dirección siguen igual.

Esperas largas y timeouts#

Los modelos de razonamiento como zai-org/GLM-5.3-Flash piensan antes de responder, así que el primer token puede tardar un rato. Usa streaming o sube el timeout del cliente — por ejemplo timeout=120 en el SDK de OpenAI.

Etiquetas: