Para agentes de IA: guia passo a passo de configuração — /docs/agents.md, índice da documentação — /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.

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

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.

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.

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

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

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

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

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