Esquema de erros
Utilizamos códigos de resposta HTTP padrão para notificações de sucesso e falha, e nossos erros são classificados adicionalmente por tipo.400 Bad Request
- Status:
400 - Possíveis valores de erro:
validation_error,invalid_certificate_type,missing_cnpj_fields,underage_holder,invalid_voucher_id. - Details:
{ "fieldErrors": { "<campo>": ["<motivo>"] } }quando há ao menos um campo com erro; omitido se não houverfieldErrors. - Ação sugerida: confira error, message e details para identificar o campo. Não tente novamente sem corrigir — o resultado vai ser o mesmo.
401 — Unauthorized
- Status:
401 - Error:
missing_or_invalid_authorization - Message: Header Authorization ausente ou malformado.
- Ação sugerida: verifique o header Authorization: Bearer czk_live_… Se a chave foi revogada, gere uma nova em /reseller/api-keys.
402 — Payment required
- Status:
402 - Error:
insufficient_credits - Message: Saldo da carteira insuficiente para emitir 1 certificado.
- Ação sugerida: recarregue a carteira e reenvie a mesma requisição.
403 — Forbidden
- Status:
403 - Error:
partner_not_approved - Message: Parceiro não aprovado.
- Ação sugerida: confirme que a conta está aprovada no portal e que o partnerId na URL é o seu.
404 — Not found
- Status:
404 - Error:
voucher_not_found - Message: Voucher não encontrado.
- Ação sugerida: confirme o identificador consultado.
409 — Conflict
- Status:
409 - Error:
duplicate_reference_id - Message:
reference_idjá utilizado para este parceiro. - Ação sugerida: use um reference_id novo, ou consulte o voucher já criado via
GET /vouchers/{voucher_id}.
422 — Unprocessable entity
- Status:
422 - Error:
invalid_reference_id - Message:
reference_idinválido ou ausente. - Ação sugerida: Confira details para ver qual campo precisa ser ajustado.
429 — Too many requests
- Status:
429 - Error:
rate_limit_exceeded - Message: Limite de requisições excedido.
- Ação sugerida: Reduza a taxa de requisições.
500 — Internal server error
- Status:
500 - Error:
internal_error - Message: Erro interno do servidor.
- Ação sugerida: Algo inesperado aconteceu do nosso lado. Por favor, entre em contato conosco para que possamos investigar o ocorrido.