> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useaira.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Respostas de erro

> Entenda o formato de erros e os códigos de status HTTP retornados pela API da Aira.

> Todas as respostas de erro da API seguem um formato consistente para facilitar o tratamento programático e a depuração.

<h2 id="estrutura-da-resposta-de-erro">
  Estrutura da resposta de erro
</h2>

```json theme={null}
{
  "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 |

<br />

<h2 id="codigos-de-status-http">
  Códigos de status HTTP
</h2>

| 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 |

<br />

<h2 id="codigos-de-erro-comuns">
  Códigos de erro comuns
</h2>

### 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               |

<h3 id="autenticacao">
  Autenticação
</h3>

| 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                 |

<br />

<h2 id="proximos-passos">
  Próximos passos
</h2>

* [Autenticação](/api-reference/autenticacao) — configure sua chave de API
* [Webhooks](/api-reference/webhooks) — receba notificações sobre mudanças de status