Erros da API de chat: o que tentar de novo e o que não
Gateway de modelos + códigos de erro + novas tentativas
Uma integração com a API de chat quebra menos pelo caso feliz do que pelo que faz quando recebe um erro. Repetir uma chamada que nunca vai passar gasta tempo e esconde o problema; desistir de uma que passaria em dois segundos derruba o serviço à toa. Este texto separa os códigos do Gateway de modelos por quem resolve cada um. A tabela de referência está em Erros, na documentação.
#O formato do erro
Todo erro do Gateway tem a mesma forma, qualquer que seja o formato da chamada (OpenAI ou Anthropic):
{
"error": {
"code": "insufficient_credit",
"message": "Saldo de créditos insuficiente. Recarregue para continuar.",
"request_id": "..."
}
}- Decida pelo
code, não pela mensagem. A mensagem é para uma pessoa ler e pode mudar de redação; o código é o contrato. - Guarde o
request_id. Ele vem também no cabeçalhox-aiuby-request-id, inclusive nas respostas com sucesso. É o que a nossa equipe pede para localizar uma chamada. - O erro nunca traz conteúdo devolvido pelo provedor, nem a sua mensagem de volta.
#Erros da requisição: corrija e mande de novo
| HTTP | Código | O que aconteceu |
|---|---|---|
| 400 | invalid_request | Corpo que não é JSON, falta de model ou messages, campo que o Gateway não aceita, ou ferramenta executada no provedor |
| 413 | payload_too_large | Corpo acima de 4 MB |
| 422 | sensitive_data_blocked | A mensagem tem dado sensível e a política do workspace manda bloquear |
| 422 | sensitive_output_blocked | A resposta do modelo tinha dado sensível e foi retida |
Nenhum desses melhora sozinho: a mesma requisição dá o mesmo erro. O invalid_request aparece muito em quem aponta uma biblioteca pronta para o Gateway, porque ele recusa campo que não conhece em vez de ignorar. No bloqueio por dado sensível, a mensagem diz qual tipo de dado foi encontrado, sem repetir o dado.
#Erros de permissão: alguém precisa liberar
| HTTP | Código | Quem resolve |
|---|---|---|
| 401 | unauthenticated | Você: o token está ausente, errado, vencido ou foi revogado |
| 403 | forbidden | Quem criou a chave: falta o escopo gateway:invoke, ou a chave não tem workspace |
| 403 | product_not_active | O dono: a organização não tem o Models ativo |
| 403 | model_not_allowed | Dono ou administrador: o modelo não está liberado no workspace |
| 403 | model_restricted | Dono ou administrador: há uma regra que tira esse modelo de quem criou a chave |
| 403 | model_unpriced | O dono: o modelo não tem preço cadastrado e modelos sem preço não foram liberados |
| 403 | budget_not_configured | O dono: o workspace não tem orçamento definido |
O que é comum a todos: a plataforma nega quando algo não foi configurado, em vez de liberar. Um workspace sem orçamento não tem gasto ilimitado, tem gasto nenhum. O princípio está em Gasto bloqueado por padrão, e os escopos em Chaves de API e escopos.
#Erros de dinheiro: repetir não adianta
| HTTP | Código | Volta quando |
|---|---|---|
| 402 | billing_account_required | A organização tiver conta de faturamento |
| 402 | payment_method_required | A conta por fatura tiver forma de pagamento ativa |
| 402 | insufficient_credit | Entrar saldo: a recarga por Pix é creditada quando o pagamento confirma |
| 402 | subscription_suspended | A mensalidade pendente for paga; com saldo, ela é debitada sozinha |
| 402 | invoice_overdue | A fatura vencida for paga |
| 429 | budget_exceeded | O mês virar, ou o dono aumentar o orçamento do workspace ou da regra |
| 429 | org_budget_exceeded | O mês virar, ou o teto da organização for ajustado |
| 429 | billing_limit_reached | O mês virar, ou o limite mensal da conta por fatura for ajustado |
Atenção
Três desses erros respondem 429, o mesmo status do limite de requisições por minuto. Uma biblioteca que repete todo 429 vai insistir por horas numa chamada que só volta no mês seguinte. É o principal motivo para decidir pelo código e não pelo status.
O saldo é conferido antes de chamar o modelo, com uma reserva pelo custo máximo da chamada. Chamada negada não é cobrada.
#Erros de ritmo: espere e repita
| HTTP | Código | Limite padrão do workspace |
|---|---|---|
| 429 | rate_limited | 60 requisições por minuto |
| 429 | concurrency_limited | 20 chamadas em andamento ao mesmo tempo |
Esses dois passam sozinhos. Espere alguns segundos, com intervalo crescente e um pouco de variação entre as tentativas, para os seus processos não voltarem todos no mesmo instante. Os limites são por workspace e contam todas as chaves dele.
#Erros do provedor: repita com cuidado
| HTTP | Código | O que aconteceu |
|---|---|---|
| 502 | upstream_error | O provedor respondeu com erro, ou a resposta veio interrompida |
| 502 | upstream_unavailable | O provedor está fora do ar |
| 504 | upstream_timeout | O provedor não respondeu a tempo |
| 503 | provider_not_configured | A plataforma não tem esse provedor configurado |
| 4xx | upstream_rejected | O provedor recusou a requisição em si (por exemplo, um parâmetro que aquele modelo não aceita) |
upstream_unavailableeupstream_timeoutvalem nova tentativa, poucas vezes e com espera.upstream_errorvale uma ou duas tentativas. Se persistir, é configuração, não instabilidade.upstream_rejectedeprovider_not_configurednão melhoram com repetição.- Quando o workspace tem rota com alternativa, o Gateway já passa para o outro modelo antes de devolver o erro. O que chega até você é o que sobrou depois disso.
#Um tratamento que cobre todos
A regra cabe em duas listas: o que repetir, e o que encaminhar para alguém.
const REPETIR = new Set(['rate_limited', 'concurrency_limited', 'upstream_unavailable', 'upstream_timeout', 'upstream_error'])
const ESPERA_MS = [1000, 3000, 8000]
async function chamar(corpo) {
for (let tentativa = 0; ; tentativa += 1) {
const resposta = await fetch('https://aiuby.com/api/gateway/v1/chat/completions', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${process.env.AIUBY_TOKEN}` },
body: JSON.stringify(corpo),
})
if (resposta.ok) return resposta.json()
const { error } = await resposta.json()
const podeRepetir = REPETIR.has(error.code) && tentativa < ESPERA_MS.length
if (!podeRepetir) {
// Guarde o código e o request_id: é o que diz quem precisa agir.
throw Object.assign(new Error(error.message), { code: error.code, requestId: error.request_id })
}
await new Promise((ok) => setTimeout(ok, ESPERA_MS[tentativa] * (0.5 + Math.random())))
}
}- Erro de dinheiro vira alerta para quem cuida da conta, não nova tentativa.
- Erro de permissão vira alerta para quem administra o workspace.
- Erro de requisição é defeito do seu código: registre com o corpo que causou, sem dado sensível.
#Limites
Limite
O Gateway não devolve o cabeçalho Retry-After: o tempo de espera é escolha de quem chama. Também não há repetição automática do lado da plataforma para chamada negada por limite.
- Numa resposta em stream, uma falha do provedor depois do primeiro pedaço não vira JSON de erro: o status
200já saiu, a conexão é encerrada e o parcial conta como uso. Está em Falha no meio da resposta, na documentação. - Os limites de ritmo padrão podem ter sido ajustados na política do seu workspace; o que vale é o que o dono configurou.
- Esta lista é a do Gateway de modelos. As outras rotas da plataforma respondem com mensagem e, em alguns casos, sem código: veja Chaves de API e escopos.
Para a primeira chamada do começo ao fim, siga Sua primeira chamada à API de chat da AIUBY.



