This page is not yet available in English. Read it in Portuguese

Skip to content

Erros da API de chat: o que tentar de novo e o que não

Equipe AIUBYEngenharia de plataforma

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):

json
{
  "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çalho x-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

HTTPCódigoO que aconteceu
400invalid_requestCorpo que não é JSON, falta de model ou messages, campo que o Gateway não aceita, ou ferramenta executada no provedor
413payload_too_largeCorpo acima de 4 MB
422sensitive_data_blockedA mensagem tem dado sensível e a política do workspace manda bloquear
422sensitive_output_blockedA 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

HTTPCódigoQuem resolve
401unauthenticatedVocê: o token está ausente, errado, vencido ou foi revogado
403forbiddenQuem criou a chave: falta o escopo gateway:invoke, ou a chave não tem workspace
403product_not_activeO dono: a organização não tem o Models ativo
403model_not_allowedDono ou administrador: o modelo não está liberado no workspace
403model_restrictedDono ou administrador: há uma regra que tira esse modelo de quem criou a chave
403model_unpricedO dono: o modelo não tem preço cadastrado e modelos sem preço não foram liberados
403budget_not_configuredO 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

HTTPCódigoVolta quando
402billing_account_requiredA organização tiver conta de faturamento
402payment_method_requiredA conta por fatura tiver forma de pagamento ativa
402insufficient_creditEntrar saldo: a recarga por Pix é creditada quando o pagamento confirma
402subscription_suspendedA mensalidade pendente for paga; com saldo, ela é debitada sozinha
402invoice_overdueA fatura vencida for paga
429budget_exceededO mês virar, ou o dono aumentar o orçamento do workspace ou da regra
429org_budget_exceededO mês virar, ou o teto da organização for ajustado
429billing_limit_reachedO 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

HTTPCódigoLimite padrão do workspace
429rate_limited60 requisições por minuto
429concurrency_limited20 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

HTTPCódigoO que aconteceu
502upstream_errorO provedor respondeu com erro, ou a resposta veio interrompida
502upstream_unavailableO provedor está fora do ar
504upstream_timeoutO provedor não respondeu a tempo
503provider_not_configuredA plataforma não tem esse provedor configurado
4xxupstream_rejectedO provedor recusou a requisição em si (por exemplo, um parâmetro que aquele modelo não aceita)
  • upstream_unavailable e upstream_timeout valem nova tentativa, poucas vezes e com espera.
  • upstream_error vale uma ou duas tentativas. Se persistir, é configuração, não instabilidade.
  • upstream_rejected e provider_not_configured nã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.

javascript
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 200 já 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.