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

# Erros da API Didit: status, corpo da resposta e correções

> Erros da API da Didit: códigos HTTP, corpos de resposta, códigos de erro estáveis e quando tentar novamente. Inclui 401, 403, 409, 429 e 5xx.

A API do Didit informa uma falha com um código de status HTTP e, em quase todos os casos, com um corpo JSON.
Esta página lista o que cada status significa, qual é o formato do corpo, quais valores de `code` você pode usar em desvios condicionais e quais falhas podem ser tentadas novamente com segurança.
Baseie-se primeiro no status e depois em `code`, quando ele estiver presente, porque o texto de uma mensagem pode mudar.

## Códigos de status

| Status | O que significa | O que fazer | Tentar novamente? |
| - | - | - | - |
| `400` | A requisição é inválida: um campo não passou na validação, ou não foi possível ler uma imagem ou um documento | Corrija o problema indicado no corpo da resposta | Após corrigir |
| `401` | A chave enviada está errada, malformada, revogada ou expirada | Verifique `DIDIT_API_KEY` ou crie uma nova chave | Após corrigir |
| `402` | Não foi possível pagar pela verificação, então ela não foi executada | Recarregue seu saldo | Após recarregar |
| `403` | Nenhuma chave foi enviada, a chave não tem acesso a este recurso ou ação, a requisição veio de fora da lista de IPs da chave ou o saldo não cobre a chamada | Consulte o corpo da resposta e consulte [Erros de chave de API](#erros-de-chave-de-api) e [Créditos insuficientes](#créditos-insuficientes) | Após corrigir |
| `404` | O recurso não existe, ou uma sessão está fora dos fluxos de verificação (workflows) ou dos status da chave | Verifique o id e os limites da chave | Não |
| `409` | A requisição entra em conflito com o estado atual, por exemplo um `Idempotency-Key` reutilizado ou uma etapa que já foi executada | Leia `code` e recarregue o estado | Depende de `code` |
| `410` | O recurso expirou, por exemplo uma sessão ou um convite | Crie um novo | Não |
| `415` | O corpo da requisição não é JSON | Envie `Content-Type: application/json` | Após corrigir |
| `422` | Um endereço de carteira corresponde a mais de uma blockchain, então nada foi analisado nem cobrado | Reenvie com `blockchain` definido como um dos valores de `candidate_chains` | Após corrigir |
| `429` | Um limite de requisições ou uma cota foi atingido | Aguarde o tempo indicado em `Retry-After`; consulte [Limite de requisições](https://docs.didit.me/pt-br/integration/rate-limiting.md) | Sim, após aguardar |
| `500` | Um erro inesperado do lado da Didit | Tente novamente com backoff e entre em contato com o suporte se o erro persistir | Consulte [Novas tentativas](#novas-tentativas-e-idempotência) |
| `502` | Um serviço do qual a Didit depende retornou um erro | Leia `code` | Consulte [Novas tentativas](#novas-tentativas-e-idempotência) |
| `503` | Um serviço do qual a Didit depende está temporariamente indisponível | Leia `code` e tente novamente | Consulte [Novas tentativas](#novas-tentativas-e-idempotência) |

## Corpos de erro

Os corpos de erro não compartilham um único formato, então leia-os de forma defensiva.
O formato depende da família de endpoints:

| Formato | Onde aparece | Exemplo |
| - | - | - |
| `detail` | A maioria dos erros, incluindo autenticação, recurso não encontrado e limites de requisições | `{"detail": "You do not have permission to perform this action."}` |
| `detail` e `code` | Erros com um código estável | `{"detail": "This application was deleted.", "code": "application_deleted"}` |
| Erros de campo | Validação de entrada | `{"workflow_id": ["This field is required."]}` |
| `non_field_errors` | Validação entre campos | `{"non_field_errors": ["..."]}` |
| Um array JSON | Alguns erros de validação, como em uma chamada de simulação | `["Scenario can only be armed before the verification starts."]` |
| `error` | A maioria das APIs independentes | `{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}` |
| `error` e `code` | Erros de imagem nas APIs independentes | `{"error": "...", "code": "invalid_image"}` |
| `error` como código, com `detail` | Verificação de carteira de identidade digital | `{"error": "insufficient_credits", "detail": "..."}` |

Um `500` pode não ter nenhum corpo JSON, então trate um corpo que não possa ser analisado.

```javascript theme={null}
const raw = await response.text();
let body = {};
try {
  body = JSON.parse(raw);
} catch {
  // A 5xx response may not be JSON: rely on response.status.
}
const code = body.code ?? null;
const message = body.detail ?? body.error ?? (Array.isArray(body) ? body[0] : raw);
```

## Erros de chave de API

| O que você enviou | Status | `detail` |
| - | - | - |
| Nenhum cabeçalho `x-api-key` | `403` | `You do not have permission to perform this action.` |
| Uma chave errada, malformada ou revogada | `401` | `Authentication credentials were not provided or are invalid.` |
| Uma chave expirada | `401` | `This API key has expired.` |
| Uma chave usada de fora da sua lista de endereços IP | `403` | `This API key can't be used from this IP address.` |
| Uma chave com escopo, sem acesso a este recurso ou ação | `403` | `This API key has no access to this endpoint.` |
| Uma chave limitada a alguns fluxos ou status, em um endpoint que ela não pode usar | `403` | `This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.` |
| Uma chave limitada a alguns fluxos ou status, em uma sessão fora desses limites | `404` | `Session not found.` |
| Uma chave cuja aplicação acabou de ser excluída | `403` | `This application was deleted.`, com `"code": "application_deleted"` |

Durante alguns minutos após a exclusão de uma aplicação, a API responde com `application_deleted` e, depois disso, recusa a chave como qualquer chave errada.
Não tente novamente: a aplicação e suas chaves foram excluídas.

Consulte [Autenticação da API](https://docs.didit.me/pt-br/getting-started/api-authentication.md) e [Chaves de API](https://docs.didit.me/pt-br/console/api-keys.md) para entender como as chaves e seus limites funcionam.

## Créditos insuficientes

Cada família de APIs informa saldo insuficiente de uma forma diferente:

| Chamada | Status | Corpo |
| - | - | - |
| `POST /v3/session/` | `400` | `{"detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}` |
| A maioria das APIs independentes | `403` | `{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}` |
| `POST /v3/bank/account-check/` | `402` | `{"detail": "...", "code": "insufficient_credits"}` |
| Verificação de carteira de identidade digital | `403` | `{"error": "insufficient_credits", "detail": "..."}` |
| Transações, Travel Rule e validação de endereço | `403` | `{"detail": "...", "code": "insufficient_credits"}` |

Em um contrato, a criação de uma sessão retorna `403` com `"code": "contract_billing_suspended"` enquanto os serviços pagos estiverem pausados para sua organização.
[Aplicações sandbox](https://docs.didit.me/pt-br/integration/sandbox-testing.md) nunca são cobradas, por isso não são submetidas a essas verificações.

## Códigos de erro

Estes valores de `code` são estáveis, então você pode tomar decisões condicionais com base neles.
A maioria aparece ao lado de `detail`; na verificação com carteiras de Digital ID, o código é o valor de `error`.

### Acesso e faturamento

| Código | Status | Significado |
| - | - | - |
| `insufficient_credits` | `402`, `403` | O saldo não é suficiente para cobrir a requisição |
| `contract_billing_suspended` | `403` | Os serviços pagos estão pausados para esta organização |
| `contract_rate_missing` | `402`, `403` | O contrato não tem tarifa para esta verificação |
| `application_deleted` | `403` | A aplicação da chave foi excluída |
| `organization_deleted` | `403` | A organização da chave foi excluída |
| `event_monitoring_disabled` | `403` | A ingestão de eventos não está ativada para esta aplicação |
| `networks_not_entitled` | `403` | As redes antifraude não estão habilitadas para esta organização |

### Requisições e idempotência

| Código | Status | Significado |
| - | - | - |
| `invalid_image` | `400` | Não foi possível usar a imagem |
| `return_url_invalid` | `400` | A URL de retorno não é permitida |
| `idempotency_key_invalid` | `400` | O `Idempotency-Key` tem mais de 255 caracteres |
| `idempotency_key_reused` | `409` | A chave já foi usada com um corpo de requisição diferente |
| `idempotency_key_in_progress` | `409` | A primeira requisição com esta chave ainda está em execução; aguarde o `Retry-After` |
| `verification_in_progress` | `409` | O usuário está concluindo esta verificação neste momento, por isso ela não pode ser cancelada; aguarde o `Retry-After` |
| `feature_override_not_pending` | `409` | A substituição já foi aplicada ou foi cancelada |

### Verificações bancárias, de telefone e de risco

| Código | Status | Significado |
| - | - | - |
| `invalid_account_input` | `400` | Os dados da conta não são válidos |
| `country_not_covered` | `404` | A verificação não cobre este país ou este tipo de conta |
| `bank_not_covered` | `404` | A verificação não cobre este banco |
| `bank_verification_not_available` | `404` | A Bank Verification ainda não está disponível |
| `account_check_unavailable` | `503` | A verificação está temporariamente indisponível e a requisição não foi cobrada |
| `phone_provider_unavailable` | `502` | A Verificação de telefone está temporariamente indisponível; nada é cobrado e nenhuma tentativa é consumida |
| `risk_lookup_unavailable` | `502` | A consulta de risco está temporariamente indisponível e a requisição não foi cobrada |

### Verificação de empresas (KYB)

| Código | Status | Significado |
| - | - | - |
| `kyb_registry_provider_unavailable` | `502` | O registro de empresas está temporariamente indisponível |
| `kyb_registry_country_unsupported` | `400` | A busca no registro não cobre este país |
| `kyb_registry_search_limit_reached` | `429` | A aplicação atingiu seu limite de 600 buscas pagas por hora |
| `kyb_session_not_writable` | `409` | A sessão foi finalizada |
| `kyb_step_mismatch` | `409` | A sessão está em outra etapa; `next_step` indica qual |
| `kyb_no_party_drafts` | `409` | Não há partes em rascunho para enviar |
| `kyb_parties_already_submitted` | `409` | As partes já foram enviadas |
| `kyb_party_kyc_session_not_deleted` | `409` | A verificação da parte ainda está ativa, por isso não pode ser gerada novamente |

### Carteiras de Digital ID

| Código | Status | Significado |
| - | - | - |
| `wallet_unavailable` | `403` | Esta carteira não está disponível para sua aplicação |
| `wallet_provider_unavailable` | `502` | Não foi possível iniciar a carteira, e nada foi criado |
| `wallet_not_configured` | `503` | Este ambiente não consegue acessar a carteira |

### Relatórios e casos

| Código | Status | Significado |
| - | - | - |
| `report_deletion_pending` | `409` | O relatório está sendo excluído; repita a exclusão para terminar de apagar seus arquivos |
| `report_storage_unavailable` | `503` | Não foi possível apagar os arquivos do relatório; repita a exclusão |
| `wallet_address_deletion_incomplete` | `503` | Não foi possível excluir um arquivo armazenado, por isso a exclusão foi interrompida; tente novamente |
| `case_request_not_waiting` | `409` | A requisição não está mais aguardando o cliente, então não há nada de que lembrá-lo |
| `case_request_reminder_too_soon` | `429` | Um lembrete foi enviado recentemente; `retry_at` indica quando você pode enviar o próximo |

### Assinaturas eletrônicas

| Código | Status | Significado |
| - | - | - |
| `signature_not_found` | `404` | A assinatura não existe |
| `signature_field_not_found` | `404` | O campo de assinatura não existe |
| `signature_not_signed` | `404`, `409` | O documento não foi assinado |

Na criação da sessão, os problemas de documento abaixo chegam como o valor do campo com problema, com status `400`, por exemplo `{"sign": "signature_document_changed"}`:

| Valor | Significado |
| - | - |
| `signature_document_changed` | O documento é diferente do enviado primeiro |
| `signature_document_not_supported` | O formato do documento não é compatível |
| `signature_document_conversion_failed` | Não foi possível converter o documento |
| `field_anchor_not_found` | A âncora de texto de um campo não foi encontrada no documento |
| `field_value_missing` | Um campo não tem valor |

### Webhooks

| Código | Status | Significado |
| - | - | - |
| `webhook_url_missing` | `400` | A entrega não tem URL registrada, então nada é enviado |
| `invalid_webhook_payload` | `400` | Os dados do webhook não estão em um formato válido |
| `webhook_resend_error` | `400` | Não foi possível assinar novamente a entrega armazenada, ou não foi possível concluir a tentativa |

## Novas tentativas e idempotência

Algumas falhas podem ser repetidas com segurança e outras não:

* **`429`:** aguarde o tempo indicado no cabeçalho `Retry-After` e tente novamente.
* **`502` e `503`:** tente novamente com backoff quando a referência do endpoint indicar que nada foi cobrado, como acontece nas verificações de telefone, e-mail, bancárias e de risco.
* **`502` em `POST /v3/database-validation/`:** leia primeiro cada entrada de `validation_errors`, porque esse status sozinho não significa uma falha temporária.
* **`503` em uma exclusão:** repita a mesma requisição até que ela retorne `200`.
* **Outros `4xx`:** corrija a requisição primeiro, porque a mesma requisição falha da mesma forma.

`POST /v3/aml/` e a verificação da carteira Digital ID aceitam um cabeçalho `Idempotency-Key` de até 255 caracteres.
Repetir uma requisição com a mesma chave e o mesmo corpo reproduz a resposta armazenada, de modo que o processamento e a cobrança acontecem uma única vez.
A mesma chave com um corpo diferente responde `409`, e, enquanto a primeira requisição ainda estiver em execução, os endpoints de carteira respondem `409` com `Retry-After`.

`POST /v3/session/` não tem chave de idempotência; por isso, se uma requisição de criação atingir o tempo limite, liste suas sessões por `vendor_data` antes de criar outra.

## Conteúdos relacionados

* [Limite de requisições](https://docs.didit.me/pt-br/integration/rate-limiting.md): limites, cabeçalhos e o corpo do `429`.
* [Autenticação da API](https://docs.didit.me/pt-br/getting-started/api-authentication.md): como enviar sua chave.
* [Testes no sandbox](https://docs.didit.me/pt-br/integration/sandbox-testing.md): reproduza resultados sem dados reais nem faturamento.
* [Webhooks](https://docs.didit.me/pt-br/integration/webhooks.md): entrega, novas tentativas e ordem.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.