Erros

Erros respondem JSON no formato {"error": "<código>"} e nunca ecoam o que você enviou. Decida pelo status HTTP; o código detalha.

json

{ "error": "not_completed" }

HTTP	error	Quando	O que fazer
401	`unauthorized`	Sem chave; chave inválida, revogada ou expirada; chave sem o escopo da rota; empresa suspensa.	Confira a chave e os escopos; não repita.
404	`not_found`	Documento inexistente ou de outra empresa.	Confira o `id`.
409	`version_conflict`	`Idempotency-Key` já usada com outra entrada.	Use outra chave para o envio diferente.
409	`not_completed`	Resultado pedido antes da liberação.	Espere o webhook `completed` ou consulte a situação mais tarde.
413	`pdf_too_large`	PDF acima de 25 MiB.	Reduza o arquivo; não repita igual.
413	`body_too_large`	Corpo acima do limite de transporte.	Reduza o arquivo; não repita igual.
422	`pdf_and_idempotency_key_required`	Falta o cabeçalho `Idempotency-Key` ou `Content-Type: application/pdf`.	Corrija os cabeçalhos.
422	`invalid_pdf`	O corpo não começa com `%PDF-`.	Envie o PDF bruto.
422	`invalid_request`	`cnpj`, `period_end` ou `entity` inválido, ou `Idempotency-Key` vazia ou acima de 128 caracteres.	Corrija a requisição.
429	`too_many_requests`	Sua chave já tem dois envios em andamento; vem com `Retry-After`.	Espere o `Retry-After` e repita com a mesma `Idempotency-Key`.
500	`internal_error`	Falha inesperada.	Repita com a mesma `Idempotency-Key` e backoff.
503	`capacity_busy`	Capacidade ocupada; vem com `Retry-After`.	Espere o `Retry-After` e repita com a mesma `Idempotency-Key`.

Observações

Parâmetros e cabeçalhos são validados antes da chave: com cnpj inválido, a resposta é 422 mesmo sem chave válida.
Respostas do proxy (por exemplo 413, 502 ou 504) podem vir sem JSON. Trate o status mesmo quando o corpo não for JSON.
502 e 504 vêm do proxy: repita com a mesma Idempotency-Key, como num timeout.
Não repita os demais 4xx sem corrigir a requisição.

O SDK transforma cada resposta de erro numa classe; todas herdam de FinstatError e trazem code e statusCode.

Classe	Quando
`FinstatAuthenticationError`	`401`: chave inválida, revogada, sem escopo ou empresa suspensa.
`FinstatNotReadyError`	`409` `not_completed`: ainda sem liberação.
`FinstatIdempotencyError`	`409` `version_conflict`: chave reutilizada com outro conteúdo.
`FinstatInvalidRequestError`	Demais `4xx` (`code` traz o motivo).
`FinstatRateLimitError`	`429` ou `503` depois das novas tentativas.
`FinstatAPIError`	`5xx` depois das novas tentativas.
`FinstatConnectionError`	Rede ou tempo esgotado.
`FinstatSignatureVerificationError`	Webhook sem assinatura válida.