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

# Erros

> Formato de erro e códigos de status usados pela API

Toda resposta de erro segue o mesmo formato:

```json theme={null}
{ "error": "descrição legível do problema" }
```

## Códigos de status

| Status | Quando acontece                                                                                                                                                                       |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | Header `X-API-Key` ausente, com chave inválida, ou chave revogada.                                                                                                                    |
| `404`  | Recurso não encontrado — inclui um `uuid` de análise/relatório que existe, mas pertence a outra empresa (por segurança, tratado como inexistente).                                    |
| `422`  | Corpo da requisição inválido, ou uma regra de negócio não foi satisfeita (ex.: pedir regeneração de uma seção determinística do relatório, ou gerar relatório fora da janela de 24h). |
| `500`  | O workflow (análise ou relatório) falhou durante a execução. Nada é persistido — repetir a chamada é seguro.                                                                          |
| `502`  | A API do motor de risco está temporariamente indisponível.                                                                                                                            |

<Tip>
  `401` e `404` nunca distinguem "não existe" de "existe mas não é seu" — é
  proposital, para não vazar a existência de dados de outras empresas.
</Tip>

## Idempotência

`POST /analyses` e `POST /reports` **não são idempotentes** — cada chamada
roda o workflow do zero e gera um novo `uuid`. Para reconsultar um resultado
já gerado, use `GET /analyses/{uuid}` ou `GET /reports/{uuid}`, não repita o
`POST`.