Referência da API
Erros e rate limits
Formato dos erros, códigos de status, rate limits e quais falhas vale a pena repetir.
Os erros voltam com um status fora da faixa 2xx e um único campo detail, com
uma mensagem legível. Ramifique pelo status HTTP.
{
"detail": "chave de acesso inválida"
}As rotas de imagem são a exceção: uma recusa
vinda do servidor de imagem usa o formato da OpenAI, com um campo code
estável em que você pode ramificar. Os status desta página continuam
valendo lá.
As mensagens podem vir em português independentemente do idioma da
requisição — trate o detail como texto de diagnóstico para logs, não como
algo a mostrar para o usuário final do jeito que vem.
Códigos de status
| Status | Significado | Repetir? |
|---|---|---|
400 | Requisição malformada — corpo inválido ou (nas rotas de extração) um arquivo grande demais para a janela de contexto do plano | Não — corrija a requisição |
401 | Chave ausente, inválida ou expirada | Não |
403 | A chave não pode usar isto — por exemplo, um model fora do seu plano (veja Modelos) | Não — escolha um modelo do seu plano ou faça upgrade |
404 | Endpoint desconhecido | Não |
413 | Corpo da requisição, arquivo, número de páginas ou schema acima do limite do plano | Não — reduza ou divida |
422 | max_tokens fora do intervalo aceito | Não — corrija o valor |
429 | O rate limit por chave, a cota diária de tokens ou a cota mensal de requisições do plano foi atingida — veja Rate limits | Sim, respeitando o header Retry-After — exceto quota_exceeded, que só se resolve quando a cota renova |
502 | O modelo não devolveu uma saída compatível com a requisição (por exemplo, JSON restrito por schema) | Às vezes — veja a tabela de erros do próprio endpoint |
503 | O modelo está carregando ou momentaneamente sem capacidade — veja Rate limits | Sim, respeitando o header Retry-After |
/v1/documents/extract, /v1/images/extract, /v1/documents/generate e as
rotas de imagem acrescentam alguns status além desta tabela — veja
Extração estruturada,
Geração de PDF e
Imagem, a única que pode
devolver 504.
Repetindo requisições
Repita só 429 e 503, esperando o número de segundos indicado em
Retry-After — e não quando a resposta disser x-should-retry: false. Repetir um 4xx nunca dá certo — só gasta uma requisição sem
nenhum ganho.
async function withRetry(fn: () => Promise<Response>, attempts = 5) {
for (let attempt = 0; ; attempt++) {
const res = await fn();
if (res.status !== 429 && res.status !== 503) return res;
if (res.headers.get("x-should-retry") === "false") return res;
if (attempt >= attempts - 1) return res;
const wait = Number(res.headers.get("Retry-After") ?? 5);
await new Promise((resolve) => setTimeout(resolve, wait * 1000));
}
}Enquanto o modelo carrega, o Retry-After pode ficar em torno de um minuto.
Dê ao seu cliente HTTP um timeout generoso (120s é um padrão seguro) para que
ele não desista antes de o loop de repetição ter a chance de funcionar.
Rate limits
Nenhum destes limites é uma fila — a requisição ou passa na hora ou é recusada
com 429/503 para você repetir. As rotas de imagem são a única exceção, com
uma espera curta por uma vaga livre — veja
Imagem.
Cota mensal de requisições
Cada plano inclui um número de requisições por mês — 2.000 no Go, 5.000
no Pro e personalizado no Enterprise —, contadas por stack e renovadas a cada
ciclo de cobrança. Passando disso, a menos que o uso extra esteja ligado, as
requisições devolvem 429 com "code": "quota_exceeded" até a cota renovar. A
resposta traz Retry-After (segundos até a renovação), x-should-retry: false
(para que os SDKs da OpenAI e da Anthropic não repitam por conta própria),
X-Quota-Limit, X-Quota-Used e X-Quota-Reset. Não repita essas requisições
em loop — verifique o code e pare. Veja Modelo de preços.
Requisições por minuto
Cada chave de API tem um limite do tipo token bucket, reabastecido de forma
contínua até um teto por minuto que acompanha o plano: 60/min (Go),
120/min (Pro) ou um teto personalizado (Enterprise). Passando dele, você
recebe 429 com um Retry-After dizendo quantos segundos faltam até haver
espaço.
Cota diária de tokens
Separada do limite por minuto, e desligada por padrão: um teto de tokens
gerados por conta por dia. Onde está ativa, ultrapassá-la devolve 429 com
Retry-After: 3600. Ela pega um tipo de falha diferente do limite por minuto —
poucas requisições, cada uma gerando muitos tokens (documentos longos,
raciocínio extenso, max_tokens alto) —, que uma simples contagem de
requisições não pega.
Capacidade
O número de requisições simultâneas acompanha o plano (o Pro aguenta mais que o
Go), e não um número fixo de vagas que você precise administrar. Quando uma
requisição não pode ser atendida naquele instante, ela recebe 503 com um
Retry-After:
Retry-After | Significado |
|---|---|
| ~5s | Sem capacidade livre naquele instante — costuma se resolver na tentativa seguinte |
| ~60s | O modelo está carregando — repita depois do intervalo; isso não é uma falha |
Processar um lote grande (milhares de itens) sem limitar a concorrência do
lado do seu cliente é, na prática, a forma mais comum de cair nisso — cada
503 de um lote sobrecarregado é um item perdido, a menos que o seu código o
repita; o servidor não o coloca numa fila por você.
As rotas de extração e de geração têm, além de tudo isso, seus próprios tetos de tamanho de arquivo e de páginas/resolução, que acompanham o plano — veja a seção Limites em Extração estruturada e em Geração de PDF.