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
{
"message": "Descrição legível do erro",
"code": "error_code",
"details": [
{
"idempotencyKey": "evt-001",
"errors": [
{
"code": "future_occurred_at",
"message": "events occurring in the future cannot be recorded"
}
]
}
],
"causations": [
{
"message": "Causa subjacente do erro",
"code": "cause_code",
"details": {}
}
]
}
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 do lote falharam ao ser processados — nenhum foi gravado |
future_occurred_at | O campo occurredAt está no futuro |
duplicated_idempotency_key | Já existe um evento com esta chave de idempotência |
failed_on_previous_event_creation | O evento não foi gravado porque outro evento do lote falhou |
immutable_field_change | O envio altera campos imutáveis de um evento já gravado |
Licenças
| Código | Causa |
|---|---|
failed_to_report_license_balances | Uma ou mais leituras falharam na validação, e nenhuma foi registrada |
license_code_not_found | Não existe licença com este code no workspace |
license_balance_payload_total_mismatch | O tamanho do payload não coincide com o total |
future_license_balance_moment | O campo occurredAt está no futuro |
duplicated_license_balance_key | Duas leituras do mesmo lote repetem a mesma licença, cliente e momento |
race_condition_duplicated_license_balance | Escritas simultâneas colidiram na mesma leitura; repita a requisição |
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