# Erros, limites e retries da API

Trate Problem Details, HTTP 400, 401, 403, 404, 429 e 503; respeite Retry-After e diferencie unresolved de indisponibilidade.

Canonical: https://iabula.com/docs/errors

## Erros estruturados

Falhas usam application/problem+json com type, title, status, code, detail e request_id. Use code para decisões de integração e request_id para suporte. Não dependa da redação de title ou detail. Uma resposta HTTP não bem-sucedida deve ser tratada antes de ler campos de sucesso.

## O que cada status indica

- 400: parâmetro, schema ou cursor inválido. Corrija a entrada antes de reenviar.
- 401: credencial ausente, inválida ou revogada.
- 403: acesso/origem não autorizado. Confira seu canal; não tente fornecer secrets internos.
- 404: identificador não encontrado no catálogo.
- 429: quota ou limite de requisições. Respeite Retry-After e consulte seu plano.
- 500 ou 503: falha interna ou indisponibilidade temporária. Use retry limitado e suporte se persistir.

## Retries sem amplificar falhas

Configure timeouts, número máximo de tentativas e backoff com jitter. Respeite o Retry-After retornado e não continue uma sequência agressiva quando a quota mensal estiver esgotada. Requests autenticados podem contabilizar consumo mesmo se a resposta for um erro; os limites dependem do canal e do plano.

## unresolved não é erro

> Resolve processado com status unresolved retorna HTTP 200 e resolved: null. HTTP 503 não deve ser convertido em unresolved. Também não confunda data: [] em Search ou Relations com falha de transporte.

- [Autenticação](https://iabula.com/docs/authentication)
- [Contrato Resolve](https://iabula.com/docs/resolve)

## Recursos

- [OpenAPI JSON](https://iabula.com/openapi.json)
- [Swagger](https://iabula.com/docs/swagger)
- [Documentation index](https://iabula.com/llms.txt)