Tratamento de erros

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

{
  "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.

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.

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.

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.

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)

Começando

Agentes de IA

Buscas

Operação

Códigos

Erros que não são erros

Retentativas

​Códigos

​Erros que não são erros

​Retentativas

Códigos

Erros que não são erros

Retentativas