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

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

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.

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 e Chaves de API 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 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: limites, cabeçalhos e o corpo do 429.
Autenticação da API: como enviar sua chave.
Testes no sandbox: reproduza resultados sem dados reais nem faturamento.
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: status, corpo da resposta e correções

Códigos de status

Corpos de erro

Erros de chave de API

Créditos insuficientes

Códigos de erro

Acesso e faturamento

Requisições e idempotência

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

Verificação de empresas (KYB)

Carteiras de Digital ID

Relatórios e casos

Assinaturas eletrônicas

Webhooks

Novas tentativas e idempotência

Conteúdos relacionados

​Códigos de status

​Corpos de erro

​Erros de chave de API

​Créditos insuficientes

​Códigos de erro

​Acesso e faturamento

​Requisições e idempotência

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

​Verificação de empresas (KYB)

​Carteiras de Digital ID

​Relatórios e casos

​Assinaturas eletrônicas

​Webhooks

​Novas tentativas e idempotência

​Conteúdos relacionados

Códigos de status

Corpos de erro

Erros de chave de API

Créditos insuficientes

Códigos de erro

Acesso e faturamento

Requisições e idempotência

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

Verificação de empresas (KYB)

Carteiras de Digital ID

Relatórios e casos

Assinaturas eletrônicas

Webhooks

Novas tentativas e idempotência

Conteúdos relacionados