> Para agentes de IA: guía paso a paso de configuración — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), índice de documentación — [`/llms.txt`](https://gate.joingonka.ai/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.

## Límites

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

| Límite | Valor | Al superarlo |
| --- | --- | --- |
| Solicitudes por minuto por clave | 120, ventana de 60 s desde la primera solicitud | `429 rate_limit_exceeded` y cabecera `Retry-After`; los rechazos 5xx de la pasarela no consumen cuota |
| Solicitudes simultáneas de la cuenta | limitadas | las sobrantes esperan en cola; si no llegan a tiempo, `429 queue_timeout` |
| Tamaño del cuerpo de la solicitud | 16 MiB | `413` |
| Longitud de la respuesta | [por modelo: tabla abajo](https://gate.joingonka.ai/es/docs/errors#max-tokens) | si supera el techo del modelo, se recorta hasta el techo, sin error |
| Claves hijas | hasta 50 por clave de gestión, hasta 120 solicitudes por minuto para cada una | para subir los techos, contacta con soporte |

### 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.

| `model` | Techo | Sin streaming | En streaming |
| --- | ---: | ---: | ---: |
| `MiniMaxAI/MiniMax-M2.7` | 8192 | 1500 | 8192 |
| `deepseek-ai/DeepSeek-V4-Flash-0731` | 32768 | 1500 | 32768 |
| `zai-org/GLM-5.3-Flash` | 8192 | 3000 | 8192 |

## Timeouts

| Etapa | Valor | Qué ocurre |
| --- | --- | --- |
| Espera de un lugar en la cola | 45 s | `429 queue_timeout` con cabecera `Retry-After: 1` |
| Inicio de la respuesta de la red, streaming | 150 s | `504 upstream_timeout`; se cobra la estimación de tokens de entrada |
| Inicio de la respuesta de la red, sin streaming | 150 s | `504 upstream_timeout`; se cobra la estimación de tokens de entrada |
| Generación de la respuesta | ≈ 300 s | la red corta la generación: la respuesta llega con `finish_reason: length`; continúa con la siguiente solicitud |
| Pausa entre chunks del stream | 30 s | el stream se cierra: `finish_reason: stop` en el chunk `joingonka-stream-stalled` |
| Señal de actividad en el stream | 15 s | comentario `: keep-alive`: los clientes SSE lo ignoran |
| Apertura del stream | 30 s | hasta ese momento el rechazo llega como código de respuesta; después, como chunk `joingonka-error` |
| Respuesta temprana sin streaming | 90 s | la pasarela devuelve `200` y envía espacios cada 15 s; el JSON sigue siendo válido; un error posterior llega en el cuerpo con el campo `error` y el estado sigue siendo `200` |

> **Qué se cobra al agotarse el tiempo**
>
> Una solicitud aceptada por la red no se puede cancelar. Con `504 upstream_timeout` se cobra la estimación de tokens de entrada, los de salida no; un reintento genera un nuevo cobro. Un stream interrumpido antes del `usage` final se cobra igual. Para respuestas largas, usa `stream: true`.

## Códigos de error

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](https://gate.joingonka.ai/es/docs/errors#anthropic-errors).

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

| Respuesta | Cuándo | Qué hacer |
| --- | --- | --- |
| 400 `invalid_request_error` | Cuerpo inválido: falta `messages`, el mensaje no es un objeto, el cuerpo no es JSON; modelo desconocido — con `param`: `model` y la lista de modelos disponibles en el texto | Corrige la solicitud según el texto del error |
| 400 `invalid_request_error` `empty_content_after_normalization` | El mensaje queda vacío tras la normalización — por ejemplo, solo contenía una imagen | Añade texto al mensaje |
| 400 `invalid_request_error` `web_search_privacy_sanitization_not_supported` | Los plugins `web` y `privacy-sanitization` en la misma solicitud | Deja solo uno de los dos |
| 400 `invalid_request_error` `previous_response_id_not_supported` `conversation_not_supported` `item_reference_not_supported` `background_not_supported` `hosted_tool_choice_not_supported` | OpenAI Responses: referencia a una respuesta, conversación o elemento guardado; modo en segundo plano; requisito de herramienta integrada | Envía el historial completo en `input` |
| 400 `api_error` | La red rechazó los parámetros — por ejemplo, un valor de `reasoning_effort` fuera de su lista | Corrige el valor según el texto del error |
| 401 `authentication_error` | Clave no encontrada, revocada o con formato desconocido | Verifica la clave en la página [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) |
| 402 `insufficient_funds` | El saldo no alcanza para la estimación de la solicitud; el restante está en `balance_ngonka` | Recarga tu saldo: [gate.joingonka.ai/billing](https://gate.joingonka.ai/billing) |
| 402 `insufficient_funds` | Solicitud sin clave y no desde el sitio (`is_demo: true`) | Pasa una API key |
| 402 `child_key_limit_exceeded` | Se superó el límite de gasto de la clave — diario, mensual o total; los restantes están en `daily_remaining, monthly_remaining, total_remaining` | Sube el límite de la clave en la página [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) o espera el reinicio |
| 403 `forbidden` | Clave de gestión `gm-` en una solicitud al modelo; API key en una ruta exclusiva del panel | Para solicitudes usa la clave `jg-` o `gc-`; la gestión de la cuenta va en el panel |
| 404 `invalid_request_error` `model_not_found` | `GET /v1/models/{model}`: el modelo no está en el catálogo o está oculto temporalmente | Toma un id de `GET /v1/models` |
| 404 `invalid_request_error` `not_found` `compact_not_supported` | OpenAI Responses: `/v1/responses/{id}` y otras direcciones con estado, `/v1/responses/compact` | Guarda el historial de tu lado; para Codex CLI define tu propio id de proveedor |
| 404 `invalid_request_error` | Ruta desconocida | Verifica el método, la ruta y la dirección base |
| 413 `invalid_request_error` | El cuerpo de la solicitud supera el límite | Reduce la solicitud |
| 415 `invalid_request_error` | El cuerpo no es JSON según la cabecera: se necesita `Content-Type: application/json` | Envía `Content-Type: application/json` |
| 429 `rate_limit_exceeded` | Se superó el número de solicitudes por minuto por clave; en el cuerpo hay `rate_limit` con `limit, remaining, reset` | Espera los segundos indicados en `Retry-After` |
| 429 `rate_limit_exceeded` `upstream_rate_limited` | El modelo está sobrecargado en la red Gonka | Reintenta después de `Retry-After` o usa otro modelo — [Modelos](https://gate.joingonka.ai/es/docs/models) |
| 429 `rate_limit_exceeded` `queue_timeout` `queue_full` | Todos los cupos de la red están ocupados: la cola está llena o se agotó la espera | Reintenta después de `Retry-After` |
| 500 `server_error` | Error interno del gateway | Reintenta más tarde; si persiste, escribe al soporte e incluye `x-request-id` |
| 501 `not_implemented` | `POST /v1/embeddings`: no hay modelos de embeddings en la red | Usa otro servicio de embeddings |
| 502 `api_error` `upstream_unauthorized` | Un proveedor de la red rechazó las credenciales del gateway — tu clave está bien | Reintenta en un minuto |
| 502 `api_error` | Error de la red Gonka; `code` proviene de la red, si lo envió | Reintenta con una pausa o usa otro modelo |
| 503 `model_unavailable` `model_outage` `model_initializing` `model_unstable` `model_not_served` | El modelo no está disponible ahora según los sondeos de la red: fallo, arranque, inestabilidad o nadie lo atiende; rechazo inmediato, sin espera | Usa otro modelo — el texto del error te dirá cuál; la lista está en [Modelos](https://gate.joingonka.ai/es/docs/models) |
| 503 `service_unavailable` | No hay nodos disponibles | Reintenta más tarde |
| 504 `timeout` `upstream_timeout` | La red aceptó la solicitud pero no respondió a tiempo; se cobró la estimación de tokens de entrada | Para respuestas largas usa `stream: true`; un reintento genera un nuevo cobro |

## Errores en un stream abierto

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]`.

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

## Formato de errores de Anthropic

- `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`.

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

## Qué reintentar

- 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.