Códigos de erro¶

Toda resposta de erro segue RFC 7807 Problem Details:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.4",
  "title": "document.not_found",
  "status": 404,
  "detail": "Documento 12345 não encontrado.",
  "traceId": "00-abc...-01"
}

title — código machine-readable (ex: auth.invalid_credentials)
detail — mensagem PT-BR humana
traceId — correlation ID; logue sempre pra rastreio

Códigos comuns¶

Autenticação / Autorização¶

`title`	Status	Causa	O que fazer
`auth.unauthorized`	401	Sem `X-Api-Key` ou chave inválida/revogada	Confira o header e se a chave não foi rotacionada
`auth.scope_missing`	403	Chave existe mas não tem o escopo necessário	Peça ao cliente expandir os escopos
`auth.tenant_required`	401	Token sem `tenant_id` claim	Use a chave da integração, não JWT humano

Documentos¶

`title`	Status	Causa
`document.not_found`	404	Documento não existe ou pertence a outro tenant
`document.invalid_status`	422	Operação inválida no status atual (ex: enviar um já enviado)
`document.no_files`	422	`send` chamado sem nenhum arquivo anexado
`document.no_signers`	422	`send` chamado sem nenhum signatário
`document.invalid_pdf`	422	Arquivo enviado não é PDF válido ou >50MB
`document.concurrency`	409	Edição concorrente — leia novamente e tente de novo

Signatários¶

`title`	Status	Causa
`signer.already_signed`	422	Tentativa de remover signatário que já assinou
`signer.concurrency`	409	Edição concorrente

Plano / Billing¶

`title`	Status	Causa	O que fazer
`plan.limit_reached`	402	Cliente atingiu limite (ex: documentos/mês)	Não retentar — sinalize pro cliente
`trial_expired`	402	Trial expirado e sem plano ativo	Cliente precisa contratar
`subscription.not_found`	402	Cliente sem assinatura	Raro, fail-safe

Webhooks¶

`title`	Status	Causa
`webhook.not_found`	404	Webhook não existe ou pertence a outro tenant
`webhook.invalid_url`	422	URL não é HTTPS válido

Rate limiting¶

`title`	Status	Causa
(header `Retry-After`)	429	60 req/min/chave excedido

Troubleshooting rápido¶

Sintoma	Provavelmente é
`401` em toda chamada	Chave errada, ou no header errado (não é `Authorization`, é `X-Api-Key`)
`403` em endpoint específico	Falta escopo — peça ao cliente expandir
`402`	Limite de plano atingido
`422 document.invalid_status`	Operação inválida pro status atual
`404` em `/documents/{id}`	Documento não existe ou é de outro tenant
`429`	Backoff exponencial; respeite `Retry-After`
Webhook não chega	Veja `Configurações → Webhooks → Entregas` no portal

Em caso de dúvida que não bate com nada, abra ticket pro time Aceitou com o traceId da resposta.