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

# Erros

> Códigos de erro padrão e formato de resposta da API Pública

# Erros

A API Pública usa códigos HTTP padrão para indicar sucesso ou falha. Nas rotas documentadas aqui, há três formatos de erro: o padrão HTTP, o de validação e o de rate limit.

## Formato padrão (4xx/5xx HTTP)

Para erros como `401`, `403`, `404`, `400`:

```json theme={null}
{
  "error": "http_error",
  "message": "Mensagem descritiva do erro",
  "detail": "Mensagem descritiva do erro",
  "correlation_id": "<uuid>"
}
```

## Formato de validação (`422`)

Quando headers, path params ou body estão inválidos:

```json theme={null}
{
  "error": "validation_error",
  "message": "Dados inválidos na requisição",
  "details": [
    {
      "type": "missing",
      "loc": ["header", "X-API-Key"],
      "msg": "Field required",
      "input": null
    }
  ],
  "correlation_id": "<uuid>"
}
```

## Formato de rate limit (`429`)

```json theme={null}
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Você atingiu o limite de requisições. Por favor, aguarde 27 segundos antes de tentar novamente.",
  "retry_after_seconds": 27,
  "retry_after_message": "27 segundos"
}
```

## Tabela de códigos

| Código | Status                | Descrição               | Quando ocorre                                                         |
| ------ | --------------------- | ----------------------- | --------------------------------------------------------------------- |
| `200`  | OK                    | Requisição bem-sucedida | Operação executada com sucesso                                        |
| `201`  | Created               | Recurso criado          | POST que cria novo recurso                                            |
| `400`  | Bad Request           | Falha de regra/execução | Ex.: cupom não pôde ser gerado ou crédito de pontos falhou            |
| `401`  | Unauthorized          | Não autenticado         | API Key com formato inválido, inválida ou revogada                    |
| `403`  | Forbidden             | Sem permissão           | Conta sem `api_access` ou chave sem acesso a esta superfície          |
| `404`  | Not Found             | Recurso não encontrado  | ID inexistente ou recurso de outra empresa                            |
| `422`  | Unprocessable Entity  | Erro de validação       | `X-API-Key` ausente, campos obrigatórios ausentes ou formato inválido |
| `429`  | Too Many Requests     | Rate limit excedido     | Mais de 60 req/min por API Key nas rotas documentadas aqui            |
| `500`  | Internal Server Error | Erro interno            | Erro inesperado no servidor                                           |

## Exemplos por código

### 401 — API Key com formato incorreto

```json theme={null}
{
  "detail": "API Key inválida: formato incorreto"
}
```

### 401 — API Key inválida ou revogada

```json theme={null}
{
  "detail": "API Key inválida ou revogada"
}
```

### 403 — Plano sem acesso

```json theme={null}
{
  "detail": "Plano da empresa não permite acesso à API Pública. Faça upgrade para um plano com api_access."
}
```

### 422 — Header obrigatório ausente

```json theme={null}
{
  "detail": [
    {
      "loc": ["header", "X-API-Key"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

### 404 — Recurso não encontrado

```json theme={null}
{
  "detail": "Cliente não encontrado"
}
```

### 422 — Erro de validação

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "nome"],
      "msg": "Campo obrigatório",
      "type": "value_error.missing"
    }
  ]
}
```

### 429 — Rate limit excedido

```json theme={null}
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Você atingiu o limite de requisições. Por favor, aguarde 27 segundos antes de tentar novamente.",
  "retry_after_seconds": 27,
  "retry_after_message": "27 segundos"
}
```

### 500 — Erro interno

```json theme={null}
{
  "detail": "Erro interno do servidor. Tente novamente mais tarde."
}
```

## Boas práticas de tratamento

<Tip>
  Sempre verifique o código HTTP antes de processar a resposta. Implemente retry apenas para erros 429 e 5xx.
</Tip>

1. **401/403**: verifique se a API Key está correta e se a conta possui acesso à API pública
2. **404**: confirme que o ID existe e pertence à sua empresa
3. **422**: valide os dados antes de enviar; confira campos obrigatórios e formatos
4. **429**: implemente backoff exponencial; respeite `Retry-After` e `X-RateLimit-Reset`
5. **500**: tente novamente após alguns segundos; se persistir, entre em contato com o suporte