Guia do produto e da API

Erros

Os erros retornam como problem+json conforme RFC 9457. Toda resposta inclui correlationId; informe-o ao contatar o suporte.

Status	Significado	O que fazer
`401`	Chave ausente ou inválida	Verifique o cabeçalho X-PDFgine-Key e se a chave não foi revogada.
`402`	Cota esgotada	Faça um upgrade ou aguarde a renovação do período.
`404`	Modelo ou documento não encontrado	Verifique o código do modelo e se há uma revisão publicada.
`429`	Limite de requisições excedido	Espere os segundos indicados no cabeçalho Retry-After e tente novamente.

Os limites de requisições acompanham o plano

Os limites por minuto e por hora dos endpoints de geração são por ORGANIZAÇÃO e vêm do seu plano; a tabela abaixo os lista. Como a contagem é por organização, não por chave, adicionar outra chave de API não aumenta o limite. Uma resposta 429 informa a janela atingida no cabeçalho X-PDFgine-RateLimit-Scope: tenant-api, tenant-render-minute ou tenant-render-hour. Para tarefas em lote, envie até 100 documentos em uma solicitação /document-batches em vez de um documento por solicitação.

A resposta quando a cota acaba

HTTP/1.1 402 Payment Required
X-PDFgine-Quota-Remaining: 0
X-PDFgine-Metering-Basis: pdf-equivalent

{
  "title": "Cota de páginas excedida",
  "status": 402,
  "detail": "Seu plano esgotou a cota de páginas disponível.",
  "correlationId": "114249cb1dbc52a29026ab2eca5c4b72"
}

Retry-After e a janela

Dois limites se aplicam, um após o outro. O primeiro protege o serviço e conta por credencial: 30 solicitações por janela sem chave e 120 com chave, em uma janela de 60 segundos. O segundo vem do seu plano e conta por organização.

Plano	Documentos / minuto	Documentos / hora
Grátis	15	150
Go	30	300
Pro	60	600
Max	300	3.000

HTTP 429

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-PDFgine-RateLimit-Scope: tenant-render-minute

{
  "title": "Too many requests",
  "status": 429,
  "detail": "The request limit was exceeded. Please try again later.",
  "correlationId": "505aac87e234a7b4669e6203ac7ffcd5"
}

A janela é fixa, não deslizante: abre na primeira solicitação, todas as solicitações dentro dela consomem a mesma cota e depois a contagem reinicia. Retry-After é o número de segundos restantes; esperar esse tempo é suficiente, e tentar antes só gera outra recusa.

Os problemas mais comuns

Um 4xx repetido sem alterações falha novamente. Esses códigos indicam uma solicitação incorreta, não um serviço ocupado; apenas 429 e 5xx merecem nova tentativa.
Em um 429, a resposta já inclui Retry-After. Escolher a espera por conta própria desperdiça tempo ou leva direto à próxima recusa.
402 não é uma falha para acordar alguém às três da manhã. Significa que a cota do mês acabou; monitore X-PDFgine-Quota-Remaining e aumente o plano antes disso.
410 em um download não significa arquivo perdido. A retenção terminou: o documento foi produzido, contabilizado e removido conforme o prazo do plano.
Registrar apenas o código de status transforma uma solicitação de suporte em adivinhação. Registre correlationId junto; esse valor localiza a solicitação.