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

> ## Agent Instructions
> A API Nomos tem base em https://api.nomos.pro e autentica pelo header `x-api-key`.
> Todos os endpoints de busca são POST. Parâmetros de consulta (page, limit, sort, q, modes) vão na query string; palavras-chave e filtros vão no corpo JSON.
> `limit` é limitado a 20 resultados por página. Para conjuntos maiores, itere sobre `page`.
> Filtros de data exigem `from` e `to` juntos. Enviar apenas `to` retorna erro 400.
> Filtros por ID (authors, rapporteurs, organs, themes, situations, stakeholders) exigem IDs internos reais devolvidos por uma busca anterior. IDs inventados não geram erro: retornam zero resultados silenciosamente.
> Filtros de valor aberto (type, regimes, section, openDataResource) não são listas fechadas. Deixe-os vazios para buscar em todas as fontes.
> Para uso conversacional ou por agentes, prefira o servidor MCP hospedado da Nomos em vez de chamar a API diretamente.

# Tratamento de erros

> Códigos de status HTTP retornados pela API Nomos e como reagir a cada um.

A API usa códigos de status HTTP padrão. Respostas de erro trazem um corpo JSON com mensagem e
código estável.

```json theme={"dark"}
{
  "error": "Mensagem descritiva do erro",
  "code": "CODIGO_DO_ERRO",
  "details": {
    "field": "campo_especifico",
    "value": "valor_invalido"
  }
}
```

Trate `code` como o valor programático e `error` como texto para humanos. O campo `details` é
opcional e aparece quando a API consegue apontar o campo específico que causou o problema.

## Códigos

| Código | Nome                 | Causa                                           | O que fazer                                                                 |
| ------ | -------------------- | ----------------------------------------------- | --------------------------------------------------------------------------- |
| `400`  | Requisição inválida  | Parâmetros inválidos ou corpo malformado        | Verifique o formato. A causa mais comum é intervalo de data com apenas `to` |
| `401`  | Não autorizado       | Chave ausente ou inválida                       | Confira o header `x-api-key`                                                |
| `403`  | Proibido             | Chave válida, mas o plano não inclui o endpoint | Fale com a Nomos sobre o acesso ao produto                                  |
| `404`  | Não encontrado       | Endpoint ou recurso inexistente                 | Verifique a URL e o ID do recurso                                           |
| `429`  | Muitas requisições   | Excesso de requisições em pouco tempo           | Aguarde e tente de novo com backoff                                         |
| `500`  | Erro interno         | Falha inesperada no servidor                    | Tente novamente com backoff exponencial                                     |
| `503`  | Serviço indisponível | Indisponibilidade temporária                    | Tente novamente após um intervalo curto                                     |

## Erros que não são erros

Duas situações retornam `200` com zero resultados em vez de falhar. Ambas são fáceis de confundir
com um problema de conectividade ou autenticação.

<AccordionGroup>
  <Accordion title="Filtro por ID com um valor inexistente">
    Filtros como `authors`, `organs`, `themes` e `situations` esperam IDs internos. Um ID que não
    existe não gera `400` — a busca simplesmente não encontra nada.

    Se uma consulta retorna vazio inesperadamente, confira primeiro se os IDs vieram mesmo de uma
    resposta anterior da API.
  </Accordion>

  <Accordion title="Valor de filtro desconhecido">
    Filtros como `type`, `regimes` e `openDataResource` aceitam qualquer valor, porque os conjuntos
    crescem com o tempo. Um valor com erro de digitação é encaminhado e não corresponde a nada.

    Deixe o filtro vazio para buscar em todos os valores.
  </Accordion>
</AccordionGroup>

## Retentativas

Para `429`, `500` e `503`, use backoff exponencial com jitter. Não retente `400`, `401`, `403` nem
`404`: são erros na requisição e vão falhar de novo com os mesmos parâmetros.

```python theme={"dark"}
import time
import random
import requests

def buscar_com_retry(url, headers, payload, tentativas=5):
    for tentativa in range(tentativas):
        r = requests.post(url, headers=headers, json=payload)
        if r.status_code not in (429, 500, 503):
            return r
        if tentativa == tentativas - 1:
            r.raise_for_status()
        espera = (2 ** tentativa) + random.uniform(0, 1)
        time.sleep(espera)
```