Erros da API Didit: códigos, respostas e correções

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 e 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	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
`502`	Um serviço do qual a Didit depende devolveu um erro	Leia o `code`	Veja Tentativas
`503`	Um serviço do qual a Didit depende está temporariamente indisponível	Leia o `code` e tente novamente	Veja Tentativas

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.

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 e Chaves de API 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 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: limites, cabeçalhos e o corpo do 429.
Autenticação da API: como enviar a sua chave.
Testes no sandbox: reproduza resultados sem dados reais nem cobrança.
Webhooks: entrega, novas tentativas e ordem.

Guias

Autenticação

Model Context Protocol (MCP)

SDKs web

SDKs nativos

SDKs de servidor

Integrações

Erros da API Didit: códigos, respostas e correções

Códigos de estado

Corpos de erro

Erros de chave de API

Créditos insuficientes

Códigos de erro

Acesso e faturação

Pedidos e idempotência

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

Verificação de empresas (KYB)

Carteiras de identidade digital

Relatórios e casos

Assinaturas eletrónicas

Webhooks

Novas tentativas e idempotência

Relacionados

​Códigos de estado

​Corpos de erro

​Erros de chave de API

​Créditos insuficientes

​Códigos de erro

​Acesso e faturação

​Pedidos e idempotência

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

​Verificação de empresas (KYB)

​Carteiras de identidade digital

​Relatórios e casos

​Assinaturas eletrónicas

​Webhooks

​Novas tentativas e idempotência

​Relacionados

Códigos de estado

Corpos de erro

Erros de chave de API

Créditos insuficientes

Códigos de erro

Acesso e faturação

Pedidos e idempotência

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

Verificação de empresas (KYB)

Carteiras de identidade digital

Relatórios e casos

Assinaturas eletrónicas

Webhooks

Novas tentativas e idempotência

Relacionados