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 |
| 409 | Conflict | A requisição conflita com o que a Aira já gravou, como quando duas requisições gravam o mesmo registro ao mesmo tempo |
| 429 | Too Many Requests | Limite de leituras do workspace ou de requisições do endereço IP atingido — veja Paginação e limites |
| 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 | A mesma chave de idempotência aparece mais de uma vez no lote |
failed_on_previous_event_creation | O evento tem um campo inválido, e a message indica o campo |
immutable_field_change | O envio altera campos imutáveis de um evento já gravado |
race_condition_duplicated_idempotency_key | Duas requisições gravaram a mesma chave de idempotência ao mesmo tempo; repita a requisição |
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 |
contract_must_be_active | A ação exige um contrato ativo — vale para atualizar um contrato ativo, criar um desconto recorrente e cancelar uma instância de plano. Confira o status em GET /v1/contracts/{id}: um contrato em rascunho precisa ser ativado antes, com POST /v1/contracts/{id}/activate; um contrato cancelado ou concluído não aceita mais a ação |
cannot_update_contracts_of_other_customers | Tentativa de alterar contrato de outro cliente |
Planos
| Código | Causa |
|---|---|
plan_instance_not_active | A instância de plano não está ativa — já foi cancelada ou chegou ao fim. Confira o status em GET /v1/plan-instances/{id}; a instância não volta a ativa, então, para voltar a faturar o plano, crie uma nova instância com POST /v1/plan-instances/ |
Faturas
| Código | Causa |
|---|---|
invalid_period_range | O período informado termina antes de começar, ou passa de um mês |
invoice_cannot_be_updated | A fatura não aceita esta ação no status em que está, ou não é uma fatura avulsa |
invoice_issue_blocked | A fatura não pode ser emitida agora. Repita a requisição em alguns segundos |
Contas de pagamento
| Código | Causa |
|---|---|
tax_id_belongs_to_another_payment_account | O CNPJ ou CPF já está em uma conta de pagamento não arquivada de outro cliente não arquivado. Para seguir mesmo assim, veja CNPJ ou CPF repetido |
tax_id_belongs_to_payment_account_from_the_same_customer | O CNPJ ou CPF já está em outra conta de pagamento não arquivada do mesmo cliente. Para seguir mesmo assim, veja CNPJ ou CPF repetido |
Limites de leitura
| Código | Causa |
|---|---|
too_many_reads_in_flight | O workspace já tem 20 leituras em andamento; espere os segundos do header Retry-After e repita a leitura |
too_many_reads_per_second | O workspace já fez 50 leituras neste segundo; espere os segundos do header Retry-After e repita a leitura |
Próximos passos
- Autenticação — configure sua chave de API
- Paginação e limites — entenda as respostas
429 - Webhooks — receba notificações sobre mudanças de status