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

# Erros e limites

> O envelope de erro, o catálogo de códigos e como se comportar diante de um 429.

Todo erro responde com o mesmo envelope.

```json theme={null}
{
  "message": "E_ORIGIN_NOT_VERIFIED",
  "errors": ["E_ORIGIN_NOT_VERIFIED: integration_origin_public_id"]
}
```

| Campo     | O que é                                                         |
| --------- | --------------------------------------------------------------- |
| `message` | o código do erro. Conjunto fechado. Ramifique por ele           |
| `errors`  | mensagens legíveis, para log. O texto pode mudar; o código, não |

O texto nunca inclui o valor que você enviou, CPF, credencial ou detalhe de fornecedor.

## Catálogo

| Código                     |  HTTP | Quando                                        | Repetir                 |
| -------------------------- | ----: | --------------------------------------------- | ----------------------- |
| `E_VALIDATION_FAILURE`     | `400` | corpo malformado, CPF ou campo inválido       | não                     |
| `E_UNAUTHORIZED_ACCESS`    | `401` | chave ausente, inválida, expirada ou revogada | não                     |
| `E_FORBIDDEN`              | `403` | chave válida, sem a permissão necessária      | não                     |
| `E_NOT_FOUND`              | `404` | fluxo ou origem fora do alcance da conta      | não                     |
| `E_REF_ID_CONFLICT`        | `409` | mesmo `ref_id`, corpo diferente               | não                     |
| `E_UNSUPPORTED_MEDIA_TYPE` | `415` | `Content-Type` não é `application/json`       | não                     |
| `E_ORIGIN_NOT_VERIFIED`    | `422` | a origem ainda está aguardando validação      | quando verificada       |
| `E_RATE_LIMITED`           | `429` | teto da chave ou da integração                | sim, após `Retry-After` |
| `E_INTERNAL_SERVER_ERROR`  | `500` | falha inesperada                              | sim, com backoff        |
| `E_AUDIT_UNAVAILABLE`      | `503` | auditoria indisponível                        | sim, com backoff        |

Repetir é seguro: a criação é idempotente por `ref_id`. Mantenha o mesmo `ref_id` e você recebe a
verificação existente em vez de uma segunda.

### 401, 403 e 422

| Código | A chave  | A permissão | A origem             |
| ------ | -------- | ----------- | -------------------- |
| `401`  | inválida |             |                      |
| `403`  | válida   | falta       |                      |
| `422`  | válida   | tem         | aguardando validação |

## Limites de uso

A criação de verificações tem teto por chave e por integração. Passando dele, a resposta é
`429 E_RATE_LIMITED` com o header `Retry-After` em segundos.

```ts title="Repetir com backoff" theme={null}
async function criarComRetry(corpo: CriarVerificacao, tentativa = 0): Promise<Response> {
  const resposta = await chamarLegitimuz(corpo);
  const recuperavel = resposta.status === 429 || resposta.status >= 500;
  if (!recuperavel || tentativa >= 4) return resposta;

  const retryAfter = Number(resposta.headers.get("Retry-After"));
  const espera = Number.isFinite(retryAfter) ? retryAfter * 1000 : 2 ** tentativa * 500;
  await new Promise((r) => setTimeout(r, espera + Math.random() * 250));
  return criarComRetry(corpo, tentativa + 1);
}
```

Para evitar o teto: crie a verificação quando a pessoa for de fato iniciar a jornada, e reaproveite
a existente repetindo o `ref_id`. Precisa de um teto maior? Fale com o
[suporte](https://painel.legitimuz.com/support) com o volume esperado.

## Erros dentro da jornada

Câmera negada, captura falha, credencial expirada: esses erros acontecem no widget e chegam ao seu
código pelo callback de erro. Veja [tratamento de erros](/guides/web/best-practices/errors).