Todas as respostas de erro da API seguem um formato consistente para facilitar o tratamento programático e a depuração.
Estrutura da resposta de erro
Campos
| Campo | Tipo | Descrição |
|---|---|---|
message | string | Descrição legível do erro |
code | string | Identificador único do tipo de erro — use para tratamento programático |
details | objeto ou array | Contexto adicional (campos inválidos, erros por evento, etc.) |
causations | array | Cadeia de erros relacionados — presente apenas quando há uma causa subjacente relevante |
Códigos de status HTTP
| Status | Nome | Descrição |
|---|---|---|
| 400 | Bad Request | Requisição malformada ou com parâmetros inválidos |
| 401 | Unauthorized | Autenticação necessária ou credenciais inválidas |
| 403 | Forbidden | Sem permissão para acessar o recurso |
| 404 | Not Found | Recurso não encontrado |
| 500 | Internal Server Error | Erro interno — entre em contato com o suporte se persistir |
Códigos de erro comuns
Eventos
| Código | Causa |
|---|---|
failed_to_create_events | Um ou mais eventos falharam na validação — nenhum foi processado |
future_occurred_at | O campo occurredAt está no futuro |
duplicated_idempotency_key | Já existe um evento com esta chave de idempotência |
Autenticação
| Código | Causa |
|---|---|
invalid_api_key | Chave de API não existe ou está incorreta |
deactivated_api_key | Chave desativada |
revoked_api_key | Chave revogada permanentemente |
expired_api_key | Chave expirada |
ip_not_allowed | IP não está na lista de IPs permitidos |
Contratos
| Código | Causa |
|---|---|
contract_must_have_plan_instances | Contrato precisa de pelo menos um plano ativo para ser ativado |
cannot_update_contracts_of_other_customers | Tentativa de alterar contrato de outro cliente |
Próximos passos
- Autenticação — configure sua chave de API
- Webhooks — receba notificações sobre mudanças de status