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

# Erros

> O formato dos erros e os códigos da API.

A API responde cada erro com o status HTTP e um corpo no formato da [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html). O tipo do conteúdo é `application/problem+json`.

```json theme={null}
{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "A chamada não trouxe uma chave de API válida. Envie a chave no cabeçalho Authorization, no formato Bearer <chave>.",
  "code": "unauthorized"
}
```

## Os campos

| Campo    | O que traz                                              |
| -------- | ------------------------------------------------------- |
| `type`   | Sempre `about:blank`.                                   |
| `title`  | A frase do status HTTP, em inglês.                      |
| `status` | O status HTTP.                                          |
| `detail` | A explicação do erro, em português. O texto pode mudar. |
| `code`   | O código do erro, em inglês. O código não muda na v1.   |

Use o `code` para decidir o que o seu sistema faz. Mostre o `detail` a uma pessoa.

## O erro de validação

A resposta `422` com o código `validation_failed` traz também a lista `errors`, com um item para cada campo com erro. Os outros códigos `422` têm uma causa só, que o `code` já nomeia, e não trazem a lista.

| Campo     | O que traz                                   |
| --------- | -------------------------------------------- |
| `field`   | O nome do campo.                             |
| `code`    | O código do erro do campo, em inglês.        |
| `message` | A explicação do erro do campo, em português. |

## Os códigos

| Status | `code`                       | O que fazer                                                                                                                |
| ------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| 400    | `invalid_parameter`          | Corrija o parâmetro que o `detail` nomeia.                                                                                 |
| 401    | `unauthorized`               | Confira a chave e o cabeçalho `Authorization`.                                                                             |
| 402    | `subscription_blocked`       | Regularize a assinatura no QX.                                                                                             |
| 402    | `trial_limit_reached`        | Assine um plano no QX. A organização em teste chegou ao limite de documentos do teste.                                     |
| 403    | `organization_archived`      | Fale com o QX.                                                                                                             |
| 403    | `plan_required`              | Assine um plano pago no QX.                                                                                                |
| 404    | `not_found`                  | Confira o id. Um id de outra organização também recebe `404`.                                                              |
| 409    | `contact_exists`             | Use o contato do campo `contact`. A organização já tem um contato com esse CPF ou CNPJ.                                    |
| 409    | `idempotency_key_in_use`     | Espere alguns segundos e repita a chamada com o mesmo `Idempotency-Key`. Veja [Idempotência](/idempotency).                |
| 409    | `document_has_content`       | Envie o arquivo para um slot vazio. O documento já tem arquivo ou resposta.                                                |
| 409    | `document_locked`            | Confira o documento no QX. O documento está aprovado ou descartado, ou a coleta dele não recebe documentos.                |
| 413    | `file_too_large`             | Envie um arquivo menor. O limite é de 25 MB, e de 10 MB para o tipo sem campo de arquivo.                                  |
| 422    | `validation_failed`          | Corrija os campos da lista `errors`.                                                                                       |
| 422    | `contact_not_found`          | Crie o contato com `POST /contacts` e repita a chamada.                                                                    |
| 422    | `contact_archived`           | Restaure o contato no QX, ou use outro contato.                                                                            |
| 422    | `pack_unavailable`           | Escolha um pacote ativo. O campo `active` de `GET /packs` mostra o pacote ativo.                                           |
| 422    | `pack_not_for_contact`       | Escolha um pacote que atende o tipo do contato. O campo `required_for` do pacote mostra o tipo.                            |
| 422    | `no_email`                   | Cadastre o e-mail do contato no QX, ou crie a coleta com `send_invitation` igual a `false`.                                |
| 422    | `contact_mismatch`           | Envie o documento do contato da coleta, ou envie o documento sem `collection_id`.                                          |
| 422    | `collection_not_accepting`   | Escolha uma coleta aberta. A coleta está cancelada, arquivada ou com o parceiro, ou ainda não tem contato.                 |
| 422    | `document_type_inactive`     | Escolha um tipo de documento ativo.                                                                                        |
| 422    | `document_type_without_file` | Escolha um tipo que recebe arquivo. O tipo é um formulário sem campo de arquivo.                                           |
| 422    | `unsupported_file`           | Envie o arquivo num formato que o tipo aceita. O tipo sem campo de arquivo aceita só PDF, JPEG e PNG.                      |
| 422    | `unknown_field`              | Use a `key` de um campo que `GET /documents/{id}` mostra.                                                                  |
| 422    | `idempotency_key_reused`     | Use um valor novo de `Idempotency-Key` para a escrita nova. Veja [Idempotência](/idempotency).                             |
| 429    | `rate_limited`               | Espere os segundos do cabeçalho `Retry-After`.                                                                             |
| 429    | `daily_limit_reached`        | Espere os segundos do cabeçalho `Retry-After`. O limite volta à meia-noite, no fuso da organização.                        |
| 429    | `too_many_invalid_keys`      | Corrija a chave e espere os segundos do cabeçalho `Retry-After`.                                                           |
| 503    | `storage_unavailable`        | Repita a chamada em alguns segundos, com o mesmo `Idempotency-Key`. O QX não guardou o arquivo, e nenhum documento nasceu. |