> ## Documentation Index
> Fetch the complete documentation index at: https://docs.id.zapsign.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Erros
> Formato do erro e a lista completa de códigos que a API devolve.
Toda falha responde no mesmo formato. Ramifique pelo `code`, que é estável, e não pela `message`, que pode mudar.
```json theme={null}
{
"error": {
"type": "invalid_request",
"code": "missing_required_param",
"message": "A required parameter is missing.",
"param": "cpf",
"doc_url": "https://docs.id.zapsign.com.br/missing_required_param",
"request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
}
}
```
Categoria do erro, para tratar famílias inteiras: `invalid_request`, `authentication_error`, `not_found`, `idempotency_error`, `payment_error`, `rate_limit_error` ou `api_error`.
Código estável. É o que sua integração deve usar.
Descrição em inglês, para diagnóstico. Não mostre ao usuário final.
O campo que causou o erro. Vem só quando um campo específico é o responsável.
Link direto para o código nesta página.
Identificador da requisição. Inclua no contato com o suporte.
## 400: contrato da requisição
O corpo ou um parâmetro não bate com o formato esperado. Nada foi executado nem cobrado.
### `invalid_json`
* **Status:** 400
* **Message:** The request body is not valid JSON.
* **Ação sugerida:** Verifique se o corpo é JSON válido e se o `Content-Type` é `application/json`.
### `missing_required_param`
* **Status:** 400
* **Message:** A required parameter is missing.
* **Ação sugerida:** O campo faltante vem em `param`. Compare com o corpo esperado do endpoint.
### `invalid_param_type`
* **Status:** 400
* **Message:** A parameter has an invalid type.
* **Ação sugerida:** O campo vem em `param`. Erro comum: enviar número como string, ou `max_age_hours` entre aspas.
### `invalid_param_value`
* **Status:** 400
* **Message:** A parameter has an invalid value.
* **Ação sugerida:** O campo vem em `param`. Confira os valores aceitos na referência do endpoint.
### `invalid_idempotency_key`
* **Status:** 400
* **Message:** The Idempotency-Key header is invalid.
* **Ação sugerida:** Use de 1 a 256 caracteres, só letras, números, `-` e `_`. Um UUID serve.
### `idempotency_key_reuse`
* **Status:** 400
* **Message:** The Idempotency-Key was already used for a different request.
* **Ação sugerida:** Uma chave pertence a um corpo. Gere uma chave nova para cada operação de negócio, e reutilize a mesma só nas retentativas dela.
## 401: autenticação
### `invalid_api_key`
* **Status:** 401
* **Message:** The API key provided is invalid.
* **Ação sugerida:** Confira o cabeçalho `Authorization: Bearer sk_...`. A resposta é a mesma para chave ausente, malformada, desconhecida ou revogada, de propósito. Crie uma chave nova no [painel](https://id.zapsign.com.br/app) se precisar.
## 402: saldo
### `insufficient_balance`
* **Status:** 402
* **Message:** Insufficient balance for this validation.
* **Ação sugerida:** Recarregue no [painel](https://id.zapsign.com.br/app). Repetir a requisição não resolve.
## 403: permissão
### `insufficient_permission`
* **Status:** 403
* **Message:** The API key does not have permission to perform this action.
* **Ação sugerida:** Os endpoints de Chaves de API exigem `permission` igual a `full_access`. Uma chave `validations_access` só cria e consulta validações.
## 404: recurso
### `not_found`
* **Status:** 404
* **Message:** No such resource.
* **Ação sugerida:** Confira o `id` na URL. Um recurso de outra conta também responde 404, para não revelar a existência dele.
## 409: idempotência em andamento
### `idempotency_in_progress`
* **Status:** 409
* **Message:** A request with the same Idempotency-Key is still in progress.
* **Ação sugerida:** A requisição original ainda está sendo processada. Espere e repita com a mesma chave para receber o resultado dela.
## 413: tamanho
### `request_too_large`
* **Status:** 413
* **Message:** The request body is too large.
* **Ação sugerida:** Os corpos desta API são pequenos. Um 413 costuma indicar que você está enviando um payload que não pertence a este endpoint.
## 422: regra de negócio
O formato está certo, o conteúdo não. Todos respondem `type` igual a `invalid_request`, trazem o campo em `param` e usam a mesma `message`: `The value provided is invalid.` O `code` é que diz o motivo.
### `consent_not_granted`
* **Status:** 422
* **Param:** `consent`
* **Ação sugerida:** Envie `consent: true`. A consulta só é feita com consentimento do titular, e `false` ou ausente é recusado.
### `invalid_cpf`
* **Status:** 422
* **Param:** `cpf`
* **Ação sugerida:** Envie 11 dígitos, sem pontos nem traço. O dígito verificador é conferido.
### `invalid_phone`
* **Status:** 422
* **Param:** `phone`
* **Ação sugerida:** Use E.164, com `+` e código do país: `+5511999998888`.
### `phone_not_brazilian`
* **Status:** 422
* **Param:** `phone`
* **Ação sugerida:** O número precisa começar com `+55`. Só telefones brasileiros são atendidos.
### `phone_not_mobile`
* **Status:** 422
* **Param:** `phone`
* **Ação sugerida:** Envie um celular. Vínculo entre CPF e telefone não funciona com número fixo.
### `phone_length_invalid`
* **Status:** 422
* **Param:** `phone`
* **Ação sugerida:** Um número brasileiro tem 12 ou 13 dígitos com o código do país, isto é, DDD mais 8 ou 9 dígitos.
### `invalid_max_age_hours`
* **Status:** 422
* **Param:** `max_age_hours`
* **Ação sugerida:** Envie um inteiro entre 1 e 2400 horas, ou omita o campo para usar a janela padrão.
### `invalid_redirect_url`
* **Status:** 422
* **Param:** `redirect_url`
* **Ação sugerida:** Use uma URL `https` de host público. Endereços internos, `localhost` e IPs privados são recusados.
### `invalid_external_id`
* **Status:** 422
* **Param:** `external_id`
* **Ação sugerida:** De 1 a 256 caracteres, só letras, números, `-` e `_`. Sem barras, pontos, dois-pontos nem espaços.
## 429: limites
Detalhes e estratégia de retentativa em [Limites de uso](/limites-de-uso).
### `rate_limit_exceeded`
* **Status:** 429
* **Message:** Too many requests. Please retry after the indicated delay.
* **Ação sugerida:** Você passou da taxa da sua conta. Espere o que diz `Retry-After` e reduza o ritmo.
### `concurrency_limit_exceeded`
* **Status:** 429
* **Message:** Too many concurrent requests. Please retry after the indicated delay.
* **Ação sugerida:** Requisições demais em voo ao mesmo tempo. Limite a concorrência do seu lado com uma fila ou um pool.
### `auth_failure_limit_exceeded`
* **Status:** 429
* **Message:** Too many failed authentication attempts from this IP. Please retry after the indicated delay.
* **Ação sugerida:** Falhas de autenticação seguidas vindas do seu IP. Corrija a chave antes de repetir: continuar tentando estende o bloqueio.
## 500: erro nosso
### `api_error`
* **Status:** 500
* **Message:** An internal error occurred.
* **Ação sugerida:** Repita com espera exponencial. Se persistir, fale com o suporte com o `request_id` da resposta.