MenuLimites e códigos de erro

/

Limites e códigos de erro

A API usa códigos de status HTTP padrão. O body de erro segue o formato do cliente que você usa, então os SDKs da OpenAI e da Anthropic conseguem lê-lo como está.

Formato dos erros

Endpoints no formato OpenAI retornam um objeto error com message, type e code. Endpoints no formato Anthropic retornam "type": "error" com um objeto error contendo type e message. Erros que ocorrem no meio de um stream são enviados como um evento com o mesmo formato.

402

{
  "error": {
    "message": "GeraiPoints tidak cukup, silakan top up",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

O conteúdo de message é escrito em indonésio e pode mudar. Na lógica do programa, verifique o código de status HTTP e type/code, não o texto da mensagem.

Códigos de status

Status	type / code	Significado	O que fazer
400	`invalid_request_error`	Requisição inválida: o body não é JSON, `model` está vazio ou `messages` está ausente/vazio. Também aparece se a base URL estiver errada e o caminho virar `/v1/v1/…`.	Verifique o body e a base URL.
401	`authentication_error`	Chave de API não enviada, errada ou revogada — ou chave usada no caminho errado (chave bansos em endpoint pago, e vice-versa).	Confira a chave e a base URL — Autenticação.
402	`insufficient_quota`	GeraiPoints insuficientes para esta requisição.	Recarregue GeraiPoints e envie de novo.
403	`permission_error`	O modelo não está na allowlist desta chave, ou é exclusivo de um plano que você ainda não tem.	Adicione o modelo à allowlist da chave ou use outra chave.
404	`model_not_found`	Id de modelo desconhecido ou indisponível no momento. Nomes com prefixo, como `gp/…` ou `openai/…`, também dão 404.	Copie o id exato da lista de modelos.
413	`—`	O body da requisição é grande demais para o servidor aceitar.	Resuma o histórico da conversa ou reduza os anexos.
429	`rate_limit_error`	Requisições demais: a capacidade do modelo está esgotada ou o limite do plano Unlimited/Bansos foi excedido.	Aguarde o tempo indicado em `Retry-After` (se houver) e tente de novo com intervalos.
502	`api_error`	O serviço do modelo está ocupado ou com problemas; a requisição não é cobrada.	Tente de novo após alguns segundos ou use outro modelo.
503	`api_error`	O modelo está em manutenção ou temporariamente indisponível; a requisição não é cobrada.	Tente de novo mais tarde ou use outro modelo.

Limites de uso

Tipo	Limite
Chave paga (gk-)	Sem limite de taxa fixo por chave; o uso é limitado pelo saldo de GeraiPoints. O 429 só aparece quando a capacidade do modelo está esgotada.
Plano Unlimited	Limite de requisições por minuto e de requisições simultâneas por conta. Respostas 429 trazem `Retry-After` e `x-ratelimit-*`. Detalhes na página Unlimited.
Nível gratuito (Bansos)	Cota de requisições por dia e limite por minuto. Respostas 429 trazem `Retry-After` e `x-ratelimit-*`. Cota restante na página Bansos.
Tamanho e resposta	Bodies grandes demais são recusados com 413. O tamanho da resposta (`max_tokens`) pode ser reduzido automaticamente se o saldo não for suficiente para o valor pedido.
Chave de API	Máximo de 20 chaves ativas por conta; allowlist de até 64 modelos por chave.
Chaves de clientes	Os limites valem antes do processamento: uma requisição que ultrapassaria o limite restante é recusada. Limite único esgotado → `402 KEY_BATAS_HABIS` (aumente o limite para adicionar cota); limite diário/mensal atingido → `429 KEY_BATAS_HARIAN` / `KEY_BATAS_BULANAN` com `Retry-After`. Chave pausada → `403 KEY_DIJEDA`. Modelos -unli e bansos não funcionam com chaves de clientes.

Tentar novamente do jeito certo

Tente novamente apenas em 429, 502 e 503, com intervalos cada vez maiores (por exemplo 1, 2, 4, 8 segundos) e no máximo 2–3 tentativas.
Não tente novamente em 400, 401, 402, 403, 404 — corrija a requisição primeiro; o resultado será o mesmo.
Respeite o header Retry-After quando houver.
Cada nova tentativa é uma nova requisição cobrada. Se a causa for o timeout do app, aumente-o — veja Configurações de ferramentas agênticas.