> Para agentes de IA: guia passo a passo de configuração — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), índice da documentação — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Erros e limites

Limites de requisições, timeouts e códigos de erro do gateway. Para cada resposta, explicamos quando ela ocorre e o que fazer: repetir a requisição ou corrigi-la.

## Limites

Os números vêm do campo `limits` da resposta `GET /v1/capabilities`: lá os valores estão sempre atualizados.

| Limite | Valor | Ao ultrapassar |
| --- | --- | --- |
| Requisições por minuto por chave | 120, janela de 60 s a partir da primeira requisição | `429 rate_limit_exceeded` e cabeçalho `Retry-After`; recusas 5xx do gateway não consomem cota |
| Requisições simultâneas da conta | limitadas | as excedentes esperam na fila; se não chegarem a tempo — `429 queue_timeout` |
| Tamanho do corpo da requisição | 16 MiB | `413` |
| Comprimento da resposta | [por modelo — tabela abaixo](https://gate.joingonka.ai/pt/docs/errors#max-tokens) | acima do teto do modelo — cortado até o teto, sem erro |
| Chaves filhas | até 50 por chave de gerenciamento, até 120 requisições por minuto para cada uma | para aumentar os tetos — fale com o suporte |

### Comprimento da resposta por modelo

Sem `max_tokens`, o gateway aplica um padrão: sem streaming, mais curto para a resposta caber nos timeouts; no streaming, o teto do modelo. `max_completion_tokens` é o mesmo campo.

| `model` | Teto | Sem streaming | No 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 | O que acontece |
| --- | --- | --- |
| Espera por uma vaga na fila | 45 s | `429 queue_timeout` com cabeçalho `Retry-After: 1` |
| Início da resposta da rede, streaming | 150 s | `504 upstream_timeout`; é cobrada a estimativa de tokens de entrada |
| Início da resposta da rede, sem streaming | 150 s | `504 upstream_timeout`; é cobrada a estimativa de tokens de entrada |
| Geração da resposta | ≈ 300 s | a rede interrompe a geração: a resposta chega com `finish_reason: length` — continue com a próxima requisição |
| Pausa entre chunks do stream | 30 s | o stream é fechado: `finish_reason: stop` no chunk `joingonka-stream-stalled` |
| Sinal de atividade no stream | 15 s | comentário `: keep-alive` — clientes SSE o ignoram |
| Abertura do stream | 30 s | até esse momento a recusa chega como código de resposta; depois, como chunk `joingonka-error` |
| Resposta antecipada sem streaming | 90 s | o gateway retorna `200` e envia espaços a cada 15 s — o JSON continua válido; um erro posterior chega no corpo com o campo `error`, e o status permanece `200` |

> **O que é cobrado em caso de timeout**
>
> Uma requisição aceita pela rede não pode ser cancelada. Com `504 upstream_timeout` cobra-se a estimativa dos tokens de entrada, os de saída não; uma nova tentativa gera uma nova cobrança. Um stream interrompido antes do `usage` final é cobrado da mesma forma. Para respostas longas, use `stream: true`.

## Códigos de erro

O corpo do erro é um objeto `error` com os campos `message, type, code, param`; nem todo erro traz todos os campos. Guie-se pelo status e por `type`, e confirme com `code`: o texto de `message` pode mudar. O formato Anthropic está na seção [Formato de erros da Anthropic](https://gate.joingonka.ai/pt/docs/errors#anthropic-errors).

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

| Resposta | Quando | O que fazer |
| --- | --- | --- |
| 400 `invalid_request_error` | Corpo inválido: falta `messages`, a mensagem não é um objeto, o corpo não é JSON; modelo desconhecido — com `param`: `model` e a lista de modelos disponíveis no texto | Corrija a requisição conforme o texto do erro |
| 400 `invalid_request_error` `empty_content_after_normalization` | A mensagem fica vazia após a normalização — por exemplo, continha apenas uma imagem | Adicione texto à mensagem |
| 400 `invalid_request_error` `web_search_privacy_sanitization_not_supported` | Os plugins `web` e `privacy-sanitization` na mesma requisição | Deixe apenas um deles |
| 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: referência a uma resposta, conversa ou item salvo; modo em segundo plano; exigência de ferramenta integrada | Envie o histórico completo em `input` |
| 400 `api_error` | A rede rejeitou os parâmetros — por exemplo, um valor de `reasoning_effort` fora da lista dela | Corrija o valor conforme o texto do erro |
| 401 `authentication_error` | Chave não encontrada, revogada ou com formato desconhecido | Verifique a chave na página [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) |
| 402 `insufficient_funds` | O saldo não cobre a estimativa da requisição; o restante está em `balance_ngonka` | Recarregue o saldo: [gate.joingonka.ai/billing](https://gate.joingonka.ai/billing) |
| 402 `insufficient_funds` | Requisição sem chave e que não veio do site (`is_demo: true`) | Passe uma API key |
| 402 `child_key_limit_exceeded` | Limite de gastos da chave excedido — diário, mensal ou total; os restantes estão em `daily_remaining, monthly_remaining, total_remaining` | Aumente o limite da chave na página [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) ou aguarde o reset |
| 403 `forbidden` | Chave de gestão `gm-` em uma requisição ao modelo; API key em uma rota exclusiva do painel | Para requisições use a chave `jg-` ou `gc-`; a gestão da conta fica no painel |
| 404 `invalid_request_error` `model_not_found` | `GET /v1/models/{model}`: o modelo não está no catálogo ou está oculto temporariamente | Pegue um id de `GET /v1/models` |
| 404 `invalid_request_error` `not_found` `compact_not_supported` | OpenAI Responses: `/v1/responses/{id}` e outros endereços com estado, `/v1/responses/compact` | Guarde o histórico do seu lado; para o Codex CLI defina seu próprio id de provedor |
| 404 `invalid_request_error` | Caminho desconhecido | Verifique o método, o caminho e o endereço base |
| 413 `invalid_request_error` | O corpo da requisição ultrapassa o limite | Reduza a requisição |
| 415 `invalid_request_error` | O corpo não é JSON segundo o cabeçalho: é preciso `Content-Type: application/json` | Envie `Content-Type: application/json` |
| 429 `rate_limit_exceeded` | Número de requisições por minuto por chave excedido; no corpo há `rate_limit` com `limit, remaining, reset` | Espere os segundos indicados em `Retry-After` |
| 429 `rate_limit_exceeded` `upstream_rate_limited` | O modelo está sobrecarregado na rede Gonka | Tente de novo após `Retry-After` ou use outro modelo — [Modelos](https://gate.joingonka.ai/pt/docs/models) |
| 429 `rate_limit_exceeded` `queue_timeout` `queue_full` | Todas as vagas da rede estão ocupadas: a fila está cheia ou a espera expirou | Tente de novo após `Retry-After` |
| 500 `server_error` | Erro interno do gateway | Tente de novo mais tarde; se persistir, escreva ao suporte e inclua `x-request-id` |
| 501 `not_implemented` | `POST /v1/embeddings`: não há modelos de embeddings na rede | Use outro serviço de embeddings |
| 502 `api_error` `upstream_unauthorized` | Um provedor da rede rejeitou as credenciais do gateway — sua chave está ok | Tente de novo em um minuto |
| 502 `api_error` | Erro da rede Gonka; `code` vem da rede, se ela o enviou | Tente de novo com uma pausa ou use outro modelo |
| 503 `model_unavailable` `model_outage` `model_initializing` `model_unstable` `model_not_served` | O modelo está indisponível agora conforme os testes da rede: falha, inicialização, instabilidade ou ninguém o está atendendo; recusa imediata, sem espera | Use outro modelo — o texto do erro indica qual; a lista está em [Modelos](https://gate.joingonka.ai/pt/docs/models) |
| 503 `service_unavailable` | Não há nós disponíveis | Tente de novo mais tarde |
| 504 `timeout` `upstream_timeout` | A rede aceitou a requisição, mas não respondeu a tempo; a estimativa dos tokens de entrada foi cobrada | Para respostas longas use `stream: true`; uma nova tentativa gera nova cobrança |

## Erros em um stream aberto

Enquanto o stream não está aberto, a recusa chega com um código de resposta normal — como sem streaming. Depois de aberto, o status já é `200` e o erro chega assim:

- Chat Completions — um chunk `joingonka-error` com o campo `error`, e depois um corte sem `[DONE]`.
- Sem streaming após uma resposta antecipada — status `200` e corpo com o campo `error`.
- Anthropic Messages — evento `event: error`, e depois o stream se fecha.
- OpenAI Responses — evento `response.failed`, causa em `response.error.code`.
- Legacy Completions — `data: {"error": …}`, depois `[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 erros da Anthropic

- `POST /v1/messages` responde com o envelope da Anthropic: `{"type": "error", "error": {"type", "message"}}`.
- As recusas do gateway mantêm o `type` da tabela acima (`insufficient_funds`, `model_unavailable` e outros); neste envelope não há campo `code` — a causa está no texto.
- Erros de forma da requisição — `invalid_request_error`: faltam mensagens ou `max_tokens`, chamada de ferramenta sem nome, modelo desconhecido.
- Caminho desconhecido — `not_found_error`, corpo grande demais — `request_too_large`.

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

## O que repetir

- Após a pausa de `Retry-After`: `429`
- Com pausa crescente — 1, 2, 4 s e assim por diante: `500`, `502`, `503 service_unavailable`, `504`
- Com outro modelo: `503 model_unavailable`
- Não repetir sem mudanças — corrija a requisição, a chave ou o saldo: `400`, `401`, `402`, `403`, `404`, `413`, `415`, `501`

Cada nova tentativa após `504` gera nova cobrança da estimativa de entrada; para respostas longas ative `stream: true`.

Se o erro se repetir, escreva ao suporte e inclua `x-request-id` dos cabeçalhos da resposta.