API
Erros
O formato das respostas de erro e o significado de cada código: autenticação, saldo, política, limites e falhas do provedor.
#Formato
O Gateway responde erros sempre neste formato:
{
"error": {
"code": "insufficient_credit",
"message": "...",
"request_id": "..."
}
}As rotas da plataforma (/api/platform/*) usam o mesmo objeto error, com message e, em parte dos casos, code, sem o request_id.
A API v1 (/api/v1/*) usa o envelope { data, error, meta } e códigos próprios: veja API v1 › Erros. Nela, produto não ativo responde 404, não product_not_active.
#Códigos
| HTTP | Código | Significado |
|---|---|---|
| 400 | invalid_request | Corpo, campo ou cabeçalho inválido |
| 401 | unauthenticated | Chave ausente, inválida, vencida ou revogada |
| 402 | insufficient_credit | Saldo pré-pago zerado |
| 402 | invoice_overdue | Fatura vencida |
| 402 | billing_account_required | Organização sem conta de faturamento |
| 402 | payment_method_required | Conta por fatura sem forma de pagamento ativa |
| 402 | subscription_suspended | Mensalidade de produto sem pagamento além do prazo |
| 403 | product_not_active | A organização não tem o Models ativo |
| 403 | forbidden | Chave sem o escopo ou sem workspace |
| 403 | model_not_allowed | Modelo não liberado no workspace |
| 403 | model_restricted | Modelo restrito para quem chama |
| 403 | budget_not_configured | Workspace sem orçamento definido |
| 413 | payload_too_large | Corpo acima de 4 MB |
| 422 | sensitive_data_blocked | Dado sensível bloqueado na entrada |
| 422 | sensitive_output_blocked | Dado sensível bloqueado na saída |
| 429 | rate_limited | Limite de requisições por minuto |
| 429 | concurrency_limited | Limite de chamadas simultâneas |
| 429 | budget_exceeded | Orçamento do workspace ou de uma regra esgotado |
| 429 | org_budget_exceeded | Teto mensal da organização atingido |
| 429 | billing_limit_reached | Limite mensal de cobrança atingido |
| 502, 503, 504 | — | Falha ou demora do provedor do modelo |
#O que fazer em cada caso
Vale tentar de novo
rate_limitedeconcurrency_limited: espere e repita, com intervalo crescente.502,503e504: falha do provedor. Repita com intervalo, ou use uma rota com reserva.
Não adianta repetir
insufficient_credit: faça uma recarga em Cobrança.budget_exceeded,org_budget_exceeded: o orçamento precisa ser revisto por quem administra.model_not_allowed: libere o modelo no workspace ou use outro.sensitive_data_blocked: retire o dado do texto, ou peça a quem administra para rever a política.
Nota
Um erro de autenticação do provedor chega a você como 502, não como 401: a sua chave da AIUBY continua válida, e o problema está na conexão da plataforma com o provedor.