# Erros

> Erros no formato RFC 9457 (application/problem+json) com codigo estável, requisicao_id e lista de campos.

URL: https://precificador3d.com.br/docs/api/erros

Todo erro da API vem em `application/problem+json` (RFC 9457), com um `codigo` estável para o seu código tratar e um `requisicao_id` para o suporte. A mensagem é genérica: nunca traz detalhe interno. A exceção é o `405` (método errado numa rota que existe): ele vem do servidor, sem corpo e sem `codigo`.

```json
{
  "type": "https://precificador3d.com.br/docs/api/erros/dados_invalidos",
  "title": "Dados inválidos",
  "status": 400,
  "codigo": "dados_invalidos",
  "detail": "Confira os campos indicados.",
  "requisicao_id": "req_01HF8Z3K2M9QX",
  "erros": [
    { "campo": "itens[0].quantidade", "codigo": "fora_da_faixa" }
  ]
}
```

- `type` é o endereço da explicação do erro neste site.
- `erros` só vem em validação, um por campo, sem repetir o valor enviado.
- `limite` só vem no `429`: `chave`, `conta`, `global` ou `ip`.
- Toda resposta, de erro ou não, traz o cabeçalho `Precificador-Requisicao-Id`.

## Como tratar

- `4xx` (fora `408`, `409` e `429`): corrija antes de repetir. Repetir igual dá o mesmo erro.
- `408`: o corpo chegou devagar demais; repita com a mesma `Idempotency-Key`.
- `409` e `429`: espere os segundos de `Retry-After` e repita (com a mesma `Idempotency-Key`, se for `POST`).
- `5xx`: repita com espera crescente (1 s, 2 s, 4 s…), sempre com a mesma `Idempotency-Key`.
- Trate pelo `codigo`, não pelo texto: o texto pode mudar.

## Todos os códigos

| Status | Códigos |
| --- | --- |
| 400 | [`dados_invalidos`](https://precificador3d.com.br/docs/api/erros/dados_invalidos), [`campo_desconhecido`](https://precificador3d.com.br/docs/api/erros/campo_desconhecido), [`filtro_desconhecido`](https://precificador3d.com.br/docs/api/erros/filtro_desconhecido), [`cursor_invalido`](https://precificador3d.com.br/docs/api/erros/cursor_invalido), [`idempotencia_obrigatoria`](https://precificador3d.com.br/docs/api/erros/idempotencia_obrigatoria), [`chave_na_url`](https://precificador3d.com.br/docs/api/erros/chave_na_url) |
| 401 | [`nao_autenticado`](https://precificador3d.com.br/docs/api/erros/nao_autenticado) |
| 403 | [`escopo_insuficiente`](https://precificador3d.com.br/docs/api/erros/escopo_insuficiente), [`conta_bloqueada`](https://precificador3d.com.br/docs/api/erros/conta_bloqueada), [`modulo_desligado`](https://precificador3d.com.br/docs/api/erros/modulo_desligado), [`chave_suspensa`](https://precificador3d.com.br/docs/api/erros/chave_suspensa) |
| 404 | [`nao_encontrado`](https://precificador3d.com.br/docs/api/erros/nao_encontrado) |
| 405 | [`metodo_nao_permitido`](https://precificador3d.com.br/docs/api/erros/metodo_nao_permitido) |
| 408 | [`tempo_esgotado`](https://precificador3d.com.br/docs/api/erros/tempo_esgotado) |
| 409 | [`idempotencia_em_andamento`](https://precificador3d.com.br/docs/api/erros/idempotencia_em_andamento), [`status_mudou`](https://precificador3d.com.br/docs/api/erros/status_mudou), [`conflito`](https://precificador3d.com.br/docs/api/erros/conflito) |
| 413 | [`corpo_grande_demais`](https://precificador3d.com.br/docs/api/erros/corpo_grande_demais) |
| 415 | [`tipo_nao_suportado`](https://precificador3d.com.br/docs/api/erros/tipo_nao_suportado) |
| 422 | [`referencia_invalida`](https://precificador3d.com.br/docs/api/erros/referencia_invalida), [`saldo_insuficiente`](https://precificador3d.com.br/docs/api/erros/saldo_insuficiente), [`quantidade_invalida`](https://precificador3d.com.br/docs/api/erros/quantidade_invalida), [`idempotencia_conflito`](https://precificador3d.com.br/docs/api/erros/idempotencia_conflito), [`transicao_invalida`](https://precificador3d.com.br/docs/api/erros/transicao_invalida), [`regra_de_negocio`](https://precificador3d.com.br/docs/api/erros/regra_de_negocio) |
| 429 | [`limite_excedido`](https://precificador3d.com.br/docs/api/erros/limite_excedido), [`cota_mensal_excedida`](https://precificador3d.com.br/docs/api/erros/cota_mensal_excedida), [`concorrencia_excedida`](https://precificador3d.com.br/docs/api/erros/concorrencia_excedida) |
| 500 | [`erro_interno`](https://precificador3d.com.br/docs/api/erros/erro_interno) |
| 503 | [`indisponivel`](https://precificador3d.com.br/docs/api/erros/indisponivel) |