Para agentes de IA: guía paso a paso de configuración — /docs/agents.md, índice de documentación — /llms.txt.

Errores y límites

Límites de solicitudes, tiempos de espera y códigos de error de la pasarela. Para cada respuesta se indica cuándo se produce y qué hacer: repetir la solicitud o corregirla.

Los números provienen del campo limits de la respuesta GET /v1/capabilities: ahí siempre están los valores actuales.

Longitud de respuesta por modelo#

Sin max_tokens, la pasarela aplica un valor por defecto: sin streaming, más corto para que la respuesta quepa en los timeouts; en streaming, el techo del modelo. max_completion_tokens es el mismo campo.

El cuerpo del error es un objeto error con los campos message, type, code, param; no todos los errores incluyen todos los campos. Guíate por el estado y type, y confirma con code: el texto de message puede cambiar. El formato de Anthropic está en la sección Formato de errores de Anthropic.

{
  "error": {
    "message": "Model is currently overloaded in the Gonka network",
    "type": "rate_limit_exceeded",
    "code": "upstream_rate_limited"
  }
}

Mientras el stream no está abierto, el rechazo llega con un código de respuesta normal — igual que sin streaming. Una vez abierto, el estado ya es 200 y el error llega así:

• Chat Completions — un chunk joingonka-error con el campo error, y luego un corte sin [DONE].
• Sin streaming tras una respuesta temprana — estado 200 y cuerpo con el campo error.
• Anthropic Messages — evento event: error, y luego el stream se cierra.
• OpenAI Responses — evento response.failed, la causa en response.error.code.
• Legacy Completions — data: {"error": …}, luego [DONE].

data: {"id":"joingonka-error","object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[],"error":{"message":"Gonka network error","type":"api_error"}}

• POST /v1/messages responde con el envoltorio de Anthropic: {"type": "error", "error": {"type", "message"}}.
• Los rechazos del gateway conservan el type de la tabla de arriba (insufficient_funds, model_unavailable y otros); en este envoltorio no hay campo code — la causa está en el texto.
• Errores de forma de la solicitud — invalid_request_error: faltan mensajes o max_tokens, llamada a herramienta sin nombre, modelo desconocido.
• Ruta desconocida — not_found_error, cuerpo demasiado grande — request_too_large.

event: error
data: {"type":"error","error":{"type":"timeout","message":"Upstream timeout"}}

• Tras la pausa de Retry-After: 429
• Con pausa creciente — 1, 2, 4 s y así: 500, 502, 503 service_unavailable, 504
• Con otro modelo: 503 model_unavailable
• No reintentar sin cambios — corrige la solicitud, la clave o el saldo: 400, 401, 402, 403, 404, 413, 415, 501

Cada reintento tras 504 genera un nuevo cobro de la estimación de entrada; para respuestas largas activa stream: true.

Si el error se repite, escribe al soporte e incluye x-request-id de las cabeceras de la respuesta.