> ## 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: códigos, respostas e correções

> Todos os erros da API Didit: códigos HTTP 401, 403, 409, 429 e 5xx, formato das respostas, códigos de erro estáveis e quais podem ser repetidos.

A API da Didit comunica uma falha com um código de estado HTTP e, quase sempre, com um corpo em JSON.
Esta página indica o que significa cada estado, como é o corpo, que valores de `code` podem usar para decidir e quais as falhas que permitem tentar novamente em segurança.
Baseie-se primeiro no estado e, quando existir, no `code`, porque o texto de uma mensagem pode mudar.

## Códigos de estado

| Estado | O que significa | O que fazer | Nova tentativa? |
| - | - | - | - |
| `400` | O pedido é inválido: um campo falhou na validação, ou não foi possível ler uma imagem ou um documento | Corrija o que o corpo indica | Depois de corrigir |
| `401` | A chave enviada está errada, mal formada, revogada ou expirada | Verifique `DIDIT_API_KEY` ou crie uma nova chave | Depois de corrigir |
| `402` | Não foi possível pagar a verificação, por isso não foi executada | Carregue saldo | Depois de carregar saldo |
| `403` | Não foi enviada nenhuma chave, a chave não tem acesso a este recurso ou ação, o pedido veio de fora da lista de IP da chave, ou o saldo não cobre a chamada | Leia o corpo e veja [Erros de chave de API](#erros-de-chave-de-api) e [Créditos insuficientes](#créditos-insuficientes) | Depois de corrigir |
| `404` | O recurso não existe, ou uma sessão está fora dos fluxos ou estados da chave | Verifique o identificador e os limites da chave | Não |
| `409` | O pedido entra em conflito com o estado atual, por exemplo um `Idempotency-Key` reutilizado ou um passo que já foi executado | Leia o `code` e recarregue o estado | Depende do `code` |
| `410` | O recurso expirou, por exemplo uma sessão ou um convite | Crie um novo | Não |
| `415` | O corpo do pedido não está em JSON | Envie `Content-Type: application/json` | Depois de corrigir |
| `422` | Um endereço de carteira corresponde a mais de uma blockchain, por isso não foi feita nenhuma triagem nem cobrança | Reenvie com `blockchain` definido com um dos valores de `candidate_chains` | Depois de corrigir |
| `429` | Foi atingido um limite de pedidos ou uma quota | Aguarde o `Retry-After`; veja [Limitação de pedidos](https://docs.didit.me/pt/integration/rate-limiting.md) | Sim, depois de aguardar |
| `500` | Erro inesperado do lado da Didit | Tente novamente com intervalos crescentes e contacte o suporte se o erro continuar | Veja [Tentativas](#novas-tentativas-e-idempotência) |
| `502` | Um serviço do qual a Didit depende devolveu um erro | Leia o `code` | Veja [Tentativas](#novas-tentativas-e-idempotência) |
| `503` | Um serviço do qual a Didit depende está temporariamente indisponível | Leia o `code` e tente novamente | Veja [Tentativas](#novas-tentativas-e-idempotência) |

## Corpos de erro

Os corpos de erro não seguem um formato comum, por isso deve tratá-los com cautela.
O formato depende da família do endpoint:

| Formato | Onde aparece | Exemplo |
| - | - | - |
| `detail` | A maioria dos erros, incluindo autenticação, não encontrado e limites de pedidos | `{"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 dados de entrada | `{"workflow_id": ["This field is required."]}` |
| `non_field_errors` | Validação entre vários campos | `{"non_field_errors": ["..."]}` |
| Um array JSON | Alguns erros de validação, como numa chamada de simulação | `["Scenario can only be armed before the verification starts."]` |
| `error` | A maioria das APIs autónomas | `{"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 autónomas | `{"error": "...", "code": "invalid_image"}` |
| `error` como código, com `detail` | Verificação com carteira de identidade digital | `{"error": "insufficient_credits", "detail": "..."}` |

Um `500` pode não ter nenhum corpo JSON, por isso trate um corpo que não possa ser interpretado.

```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 enviou | Estado | `detail` |
| - | - | - |
| Nenhum cabeçalho `x-api-key` | `403` | `You do not have permission to perform this action.` |
| Uma chave errada, mal formada ou revogada | `401` | `Authentication credentials were not provided or are invalid.` |
| Uma chave expirada | `401` | `This API key has expired.` |
| Uma chave usada a partir de fora da sua lista de IP | `403` | `This API key can't be used from this IP address.` |
| Uma chave com âmbito limitado, 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 estados, num endpoint que 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 estados, numa sessão fora desses limites | `404` | `Session not found.` |
| Uma chave cuja aplicação acabou de ser eliminada | `403` | `This application was deleted.`, com `"code": "application_deleted"` |

Durante alguns minutos após a eliminação de uma aplicação, a API responde com `application_deleted`. Depois disso, recusa a chave como faria com qualquer chave errada.
Não repita o pedido: a aplicação e as suas chaves foram eliminadas.

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

## Créditos insuficientes

Cada família de APIs comunica um saldo baixo à sua maneira:

| Chamada | Estado | 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 autónomas | `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 com carteira de identidade digital | `403` | `{"error": "insufficient_credits", "detail": "..."}` |
| Transações, Travel Rule e validação de endereços | `403` | `{"detail": "...", "code": "insufficient_credits"}` |

Num contrato, a criação de uma sessão responde com `403` e `"code": "contract_billing_suspended"` enquanto os serviços pagos da sua organização estiverem suspensos.
As [aplicações sandbox](https://docs.didit.me/pt/integration/sandbox-testing.md) nunca são cobradas, por isso não passam por estas verificações.

## Códigos de erro

Estes valores de `code` são estáveis, por isso pode usá-los para ramificar a lógica do seu código.
A maioria aparece junto de `detail`; na verificação de carteiras de identidade digital, o código é o valor de `error`.

### Acesso e faturação

| Código | Estado | Significado |
| - | - | - |
| `insufficient_credits` | `402`, `403` | O saldo não cobre a chamada |
| `contract_billing_suspended` | `403` | Os serviços pagos estão suspensos 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 eliminada |
| `organization_deleted` | `403` | A organização da chave foi eliminada |
| `event_monitoring_disabled` | `403` | A ingestão de eventos não está ativada para esta aplicação |
| `networks_not_entitled` | `403` | As redes de fraude não estão ativadas para esta organização |

### Pedidos e idempotência

| Código | Estado | Significado |
| - | - | - |
| `invalid_image` | `400` | A imagem não pôde ser utilizada |
| `return_url_invalid` | `400` | O URL de retorno não é permitido |
| `idempotency_key_invalid` | `400` | O `Idempotency-Key` tem mais de 255 caracteres |
| `idempotency_key_reused` | `409` | A chave já foi usada com um corpo diferente |
| `idempotency_key_in_progress` | `409` | O primeiro pedido com esta chave ainda está em execução; aguarde o `Retry-After` |
| `verification_in_progress` | `409` | O utilizador está a concluir esta verificação neste momento, por isso não pode ser cancelada; aguarde o `Retry-After` |
| `feature_override_not_pending` | `409` | A substituição já foi aplicada ou cancelada |

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

| Código | Estado | Significado |
| - | - | - |
| `invalid_account_input` | `400` | Os dados da conta não são válidos |
| `country_not_covered` | `404` | A verificação não abrange este país nem este tipo de conta |
| `bank_not_covered` | `404` | A verificação não abrange este banco |
| `bank_verification_not_available` | `404` | A Verificação bancária não está disponível |
| `account_check_unavailable` | `503` | A verificação está temporariamente indisponível e o pedido não foi cobrado |
| `phone_provider_unavailable` | `502` | A verificação de telefone está temporariamente indisponível; nada é faturado e não é consumida nenhuma tentativa |
| `risk_lookup_unavailable` | `502` | A consulta de risco está temporariamente indisponível e o pedido não foi cobrado |

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

| Código | Estado | Significado |
| - | - | - |
| `kyb_registry_provider_unavailable` | `502` | O registo de empresas está temporariamente indisponível |
| `kyb_registry_country_unsupported` | `400` | A pesquisa no registo não abrange este país |
| `kyb_registry_search_limit_reached` | `429` | A aplicação atingiu o limite de 600 pesquisas pagas por hora |
| `kyb_session_not_writable` | `409` | A sessão está terminada |
| `kyb_step_mismatch` | `409` | A sessão está noutro passo; `next_step` indica qual |
| `kyb_no_party_drafts` | `409` | Não há rascunhos de intervenientes para submeter |
| `kyb_parties_already_submitted` | `409` | Os intervenientes já foram submetidos |
| `kyb_party_kyc_session_not_deleted` | `409` | A verificação do interveniente ainda está ativa, por isso não pode ser regenerada |

### Carteiras de identidade digital

| Código | Estado | Significado |
| - | - | - |
| `wallet_unavailable` | `403` | Esta carteira não está disponível para a sua aplicação |
| `wallet_provider_unavailable` | `502` | A carteira não conseguiu iniciar e nada foi criado |
| `wallet_not_configured` | `503` | Este ambiente não consegue aceder à carteira |

### Relatórios e casos

| Código | Estado | Significado |
| - | - | - |
| `report_deletion_pending` | `409` | O relatório está a ser eliminado; repita a eliminação para concluir a remoção dos seus ficheiros |
| `report_storage_unavailable` | `503` | Não foi possível remover os ficheiros do relatório; repita a eliminação |
| `wallet_address_deletion_incomplete` | `503` | Não foi possível eliminar um ficheiro guardado, pelo que a eliminação parou; tente novamente |
| `case_request_not_waiting` | `409` | O pedido já não aguarda o cliente, por isso não há nada de que o lembrar |
| `case_request_reminder_too_soon` | `429` | Um lembrete foi enviado há pouco; `retry_at` indica quando pode enviar o seguinte |

### Assinaturas eletrónicas

| Código | Estado | 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 com o documento indicados abaixo chegam como valor do campo em causa, com estado `400`, por exemplo `{"sign": "signature_document_changed"}`:

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

### Webhooks

| Código | Estado | Significado |
| - | - | - |
| `webhook_url_missing` | `400` | A entrega não tem um URL registado, por isso nada é enviado |
| `invalid_webhook_payload` | `400` | Os dados do webhook não estão num formato válido |
| `webhook_resend_error` | `400` | A entrega guardada não pôde ser assinada novamente, ou a tentativa não pôde ser concluída |

## Novas tentativas e idempotência

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

* **`429`:** aguarde pelo cabeçalho `Retry-After` e, em seguida, tente novamente.
* **`502` e `503`:** tente novamente com recuo 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 este estado, por si só, não significa uma falha temporária.
* **`503` numa eliminação:** repita o mesmo pedido até obter `200`.
* **Outros `4xx`:** corrija primeiro o pedido, porque o mesmo pedido falha sempre da mesma forma.

`POST /v3/aml/` e a verificação de carteira Digital ID aceitam um cabeçalho `Idempotency-Key` com até 255 caracteres.
Repetir um pedido com a mesma chave e o mesmo corpo devolve a resposta guardada, pelo que o trabalho e a cobrança são executados apenas uma vez.
A mesma chave com um corpo diferente devolve `409`, e enquanto o primeiro pedido ainda estiver em execução, os endpoints de carteira devolvem `409` com `Retry-After`.

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

## Relacionados

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


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