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

# Erros

> O envelope de erro e os códigos de status da API do Croma.

## Envelope

As respostas bem-sucedidas retornam `{ "data": … }`. As falhas retornam um
objeto `error` e um status HTTP diferente de 2xx. Ramifique pelo código de
status, não por um indicador no corpo:

```json theme={"dark"}
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param",
    "message": "String must contain at least 3 character(s)",
    "param": "name",
    "details": { "issues": [{ "path": "name", "message": "String must contain at least 3 character(s)" }] }
  }
}
```

| Campo     | Notas                                                                       |
| --------- | --------------------------------------------------------------------------- |
| `type`    | Categoria geral (veja abaixo).                                              |
| `code`    | Código específico legível por máquina. Ramifique com base neste.            |
| `message` | Legível por humanos; seguro para exibir na interface.                       |
| `param`   | Campo problemático. Presente em erros de validação.                         |
| `details` | Detalhe estruturado opcional (por exemplo, todos os `issues` de validação). |

As respostas dos endpoints de dados carregam também um cabeçalho
`X-Request-Id`; inclua-o ao reportar um problema.

## Tipos e códigos

| Status | `type`                  | `code`                         | Significado                                                                                   |
| ------ | ----------------------- | ------------------------------ | --------------------------------------------------------------------------------------------- |
| `400`  | `invalid_request_error` | `invalid_param`                | O corpo falhou na validação; veja `param` / `details`.                                        |
| `400`  | `invalid_request_error` | `too_many_results`             | A consulta correspondeu a registros demais para retornar. Restrinja-a.                        |
| `401`  | `authentication_error`  | `invalid_api_key`              | Chave ausente ou inválida.                                                                    |
| `401`  | `authentication_error`  | `personal_api_key_not_allowed` | Foi usada uma chave pessoal; apenas chaves de organização.                                    |
| `404`  | `not_found_error`       | `endpoint_not_found`           | Não há um endpoint de API nessa rota. Veja a [Referência da API](/pt/api-reference/overview). |
| `404`  | `not_found_error`       | `job_not_found`                | Não há um [trabalho assíncrono](/pt/async-jobs) com esse id na sua organização.               |
| `405`  | `invalid_request_error` | `method_not_allowed`           | Método incorreto. Os endpoints de dados são `POST`.                                           |
| `429`  | `rate_limit_error`      | `rate_limited`                 | Cota excedida; veja [Limites de taxa](/pt/rate-limits).                                       |
| `5xx`  | `upstream_error`        | `<source>_upstream`            | Uma fonte governamental falhou ou não estava disponível.                                      |
| `500`  | `api_error`             | `internal_error`               | Erro interno inesperado.                                                                      |

<Note>
  Nem todos os endpoints emitem todos os códigos; a página de referência de
  cada endpoint lista os seus. Um "sem correspondências" nunca é um `404`; é um
  `200` bem-sucedido: as consultas de registro único retornam `found: false`, e as
  buscas retornam uma lista vazia. Um `404` significa que o endpoint ou o
  id do trabalho em si não existe.
</Note>

<Note>
  As [consultas assíncronas](/pt/async-jobs) podem falhar como **trabalho** em
  vez de como um erro HTTP. Um trabalho com falha carrega o mesmo objeto `error`
  no envelope, com `code: "job_failed"`.
</Note>