# Erros

Quando uma API da Inovacc recusa ou não consegue concluir uma chamada, ela responde com um status HTTP e um envelope de erro em JSON. Este guia descreve o envelope, os tipos de erro, os códigos que todas as APIs compartilham e o que fazer para cada status: corrigir a requisição, esperar ou tentar novamente.

## O envelope

```json
{ "error": { "message": "Human-readable explanation", "type": "validation_error", "code": "invalid_body" } }
```

- **`code`** é aquilo em que o seu programa deve se basear para ramificar. Os códigos fazem parte do contrato de cada API: dentro de um caminho de versão como `/v1`, novos códigos podem ser acrescentados, e um código existente mantém o seu significado.
- **`type`** agrupa os códigos em famílias, úteis para registro em log e tratamento amplo.
- **`message`** é uma frase fixa em inglês para pessoas. Ela nunca repete um valor da sua requisição (no máximo o nome de um campo recusado) e nunca descreve o que falhou dentro da Inovacc. Não a interprete programaticamente.

Algumas respostas acrescentam um campo ao envelope: um arquivo recusado traz `reason` (por exemplo `executable` ou `password_protected`), e uma conversão de esquema que não se encaixa traz `failing_documents`, uma contagem. Ignore os campos que você não conhece.

Duas respostas não usam o envelope. Na API de IA, um caminho que não existe responde `404 {"error":"not_found"}`. Um WebSocket (uma transmissão de Eventos ou um ouvinte de Dados) recusado antes do upgrade responde com um erro HTTP comum; depois de aberto, ele termina com um código de fechamento.

## Tipos

| `type` | Significa | Status típico |
|---|---|---|
| `validation_error` | A requisição está malformada: um cabeçalho, um campo ou um valor viola as regras. | 400 |
| `invalid_request_error` | A requisição está bem formada, mas não pode ser atendida como foi enviada: grande demais, um tipo de arquivo não suportado, uma URL que não pode ser buscada. | 400, 413, 415, 422 |
| `authentication_error` | Nenhuma credencial, ou uma que não é válida. | 401 |
| `authorization_error`, `permission_error`, `forbidden` | A credencial é válida, mas não pode fazer isto. | 403 |
| `not_found_error`, `not_found` | A coisa não existe, ou você não pode saber que ela existe. | 404, 410 |
| `conflict_error`, `conflict` | A requisição entra em conflito com o estado atual: uma versão, um modo, um limite de uma coleção. | 409 |
| `idempotency_error` | Um id de operação está em uso ou foi usado para outra coisa. | 409 |
| `rate_limit_error`, `rate_limited` | Chamadas demais, ou uma cota ou orçamento foi consumido. | 429 |
| `api_error`, `service_error`, `service_unavailable`, `internal_error` | Algo do lado da Inovacc, ou uma fonte que ela chamou por você, falhou. | 500, 502, 503, 504 |

As APIs de Dados, de IA e de Eventos usam as famílias acima; a string exata de `type` pode diferir entre APIs para a mesma família, então trate o `code` e use o status HTTP como alternativa.

## Códigos que toda API compartilha

| Status | Código | Significado | O que fazer |
|---|---|---|---|
| 401 | `missing_credentials`, `invalid_credentials` | Nenhuma chave, ou uma chave que não é válida, expirou ou foi revogada. | Corrija a credencial; não tente de novo sem alterá-la. |
| 403 | `forbidden`, `route_forbidden`, `key_disabled`, `capability_not_enabled` | A credencial não pode fazer isto. | Peça a permissão, a rota ou a capacidade. |
| 403 | `origin_not_allowed`, `secret_key_in_browser` | Uma chamada de navegador a partir de uma origem não listada, ou uma chave secreta em um navegador. | Liste a origem; use uma chave publicável. |
| 400 | `missing_operation_id`, `invalid_operation_id` | IA: um `POST`, `PUT` ou `DELETE` sem um `X-Operation-Id` válido. | Envie de 8 a 128 letras, dígitos, `_` ou `-`. |
| 400 | `invalid_body`, `unsupported_field`, `invalid_field` | O corpo ou um parâmetro não é válido para este endpoint. | Corrija a requisição. |
| 404 | `*_not_found` | Não existe, ou não é seu. | Confira o id. |
| 409 | `operation_in_progress` | O mesmo id de operação ainda está em execução. | Aguarde e tente novamente com o mesmo id. |
| 409 | `operation_id_reused` | IA: um id de operação já usado para outro arquivo em uma coleção. | Use um novo id de operação para uma nova operação. |
| 409 | `version_conflict` | Dados: o registro mudou desde que você o leu. | Leia de novo e tente novamente. |
| 413 | `request_too_large`, `payload_too_large` | O corpo excede o limite de tamanho. | Reduza-o ou envie em partes. |
| 429 | `rate_limited` | Requisições demais na janela. | Aguarde `Retry-After` segundos, quando informado. |
| 429 | `quota_exceeded`, `concurrency_limited` | IA: uma cota de tokens, de custo ou de simultaneidade se esgotou. | Diminua o ritmo; peça à Inovacc para aumentar a cota. |
| 429 | `budget_exhausted` | IA: um orçamento diário foi consumido. | Aguarde até 00:00 UTC (`Retry-After`). |
| 502 | `upstream_error` | Uma fonte chamada por você falhou. | Tente novamente com espera crescente. |
| 503 | `service_unavailable` | Uma dependência não pôde ser alcançada; nada foi feito nem presumido. | Tente novamente com espera crescente. |
| 504 | `timeout_error` | IA: o modelo não começou a responder a tempo. | Tente novamente com espera crescente. |

Cada página de produto lista todos os códigos que ele pode devolver, com o que fazer.

## Política de novas tentativas

| Status | Tentar de novo? | Como |
|---|---|---|
| 400, 401, 403, 404, 410, 413, 415, 422 | Não | A mesma requisição falhará da mesma forma. Corrija-a primeiro. |
| 409 `operation_in_progress` | Sim | Após uma curta espera, com o **mesmo** id de operação. |
| 409 `version_conflict` | Sim, após reler | Leia o registro, aplique a sua alteração à nova versão, envie o `If-Match` dela. |
| 409, outros códigos | Não | O estado precisa mudar primeiro (crie o banco de dados, aguarde os itens, esvazie a pasta). |
| 429 com `Retry-After` | Sim | Não antes do número de segundos informado. |
| 429 sem `Retry-After` | Mais tarde | Uma cota se esgotou: espere minutos, não segundos, ou aumente-a. |
| 500, 502, 503, 504 | Sim | Com espera exponencial e jitter (por exemplo 1, 2, 4, 8 segundos), no máximo algumas vezes. |
| Erro de rede, sem resposta | Sim | Como para 503. |

**Repita com segurança.** Na API de IA, repita uma chamada que altera algo com o **mesmo** `X-Operation-Id`: se a primeira tentativa teve sucesso, você recebe a resposta armazenada em vez de uma segunda execução. Em Dados, repita uma criação com o seu próprio id de registro ou `If-None-Match: *`, e uma atualização com o mesmo `If-Match`. Em Eventos, repita uma publicação com a mesma `idempotency_key`: o `event_id` original volta com `duplicate: true`.

## Veja também

- [Autenticação](/pt-br/guides/authentication/): credenciais e idempotência.
- [Limites](/pt-br/guides/limits/): os tamanhos e taxas por trás de `413` e `429`.
- [Webhooks](/pt-br/guides/webhooks/): como as entregas que falharam são repetidas.