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

> Códigos de status comuns e o formato de erro de cada API

As duas APIs usam os mesmos códigos de status HTTP, mas **o corpo do erro muda de uma API para a outra**. Trate o corpo conforme a API que você chamou.

## Códigos de status comuns

| Status | Significado |
| - | - |
| `401` | Chave ausente, inválida ou rejeitada. Veja [Autenticação](https://docs.nlbs.ai/authentication.md). |
| `403` | A chave é válida, mas não tem o escopo necessário, ou a empresa não tem acesso ao recurso. |
| `404` | O recurso solicitado não existe. |
| `422` | Requisição inválida: corpo, parâmetro de rota, parâmetro de consulta ou regra de negócio. |
| `429` | Limite de uso do plano excedido. |
| `503` | Um recurso necessário está temporariamente indisponível. Repita a requisição. Quando vier com `Retry-After`, espere esse intervalo. |

## API de Anti Fraude

O corpo traz uma mensagem estável em `detail`:

```json theme={null}
{ "detail": "Análise não encontrada." }
```

Nas rotas `/analyses`, o corpo de erro traz também `elapsed_ms`, os milissegundos inteiros que o servidor gastou até montar o erro, como chave irmã de `detail`:

```json theme={null}
{ "detail": "<mensagem>", "elapsed_ms": 1243 }
```

| Status | Corpo típico |
| - | - |
| `401` | `{"detail": "Falha na autenticação."}` |
| `403` | `{"detail": "Escopo insuficiente."}` |
| `404` | `{"detail": "Análise não encontrada."}` (a mensagem varia por recurso) |
| `409` | `{"detail": "A resolução de identidade do sujeito é ambígua."}` |
| `429` | `{"detail": "quota_exceeded"}` |

O `409` ocorre quando a identidade da pessoa ou empresa consultada é ambígua.

Endpoints que criam recursos cobráveis (`POST /analyses`, `POST /reports`, `POST /adverse-media`) checam o limite do plano antes de executar. Além dos erros documentados em cada página, eles podem retornar `429` com `{"detail": "quota_exceeded"}` (limite de uso do período esgotado) ou `403` com `{"detail": "feature_not_in_plan"}` (o plano atual não inclui o recurso). Esse `403` é diferente do `403` de escopo insuficiente, embora tenha o mesmo status.

Algumas mensagens de erro do grafo vêm em inglês (por exemplo, `"Graph node was not found."`). O formato `{"detail": "<mensagem>"}` é o mesmo.

### O caso do `422`

Na API de Anti Fraude, o `422` traz `detail` como uma lista de erros por campo:

```json theme={null}
{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "name"],
      "msg": "Pelo menos um entre 'name' ou 'document' deve ser fornecido.",
      "input": null
    }
  ]
}
```

Trate `detail` como texto nos demais status e como lista de objetos apenas no `422`.

## API de Dados

O corpo traz um objeto `erro` com `codigo` e `mensagem`:

```json theme={null}
{ "erro": { "codigo": "entrada_invalida", "mensagem": "Entrada invalida nos campos: documento." } }
```

Aqui o `422` usa o mesmo formato, sem lista por campo. A lista completa de códigos está em [Erros da API de Dados](https://docs.nlbs.ai/dados/erros.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.