Erros da API e o que eles significam
O que cada status HTTP da API da Didit costuma significar na prática - 401 e 403 relacionados a chaves e permissões, problemas de saldo do tipo 402, limites de taxa 429, e como ler o corpo do erro.
Leia o corpo da resposta. Os erros da Didit trazem uma mensagem e, muitas vezes, um código de detalhe que aponta o problema real - o status sozinho raramente conta a história toda. 401 é a chave, 403 é permissão ou ambiente, 429 é limite de taxa, e um erro de saldo é sobre créditos, não sobre código.
#Leia o corpo primeiro
O status HTTP indica a categoria. O corpo indica o que aconteceu. Quase toda hora de depuração evitável em uma integração de API é gasta tentando adivinhar a partir de um código de status, enquanto a resposta estava em um corpo que foi descartado.
- Uma chave desativada ou de uma aplicação errada costuma causar um 401.
- O último uso confirma se a chave que você acha que está enviando é a que realmente chega.
- Gire o secret se uma chave pode ter vazado - um 401 é melhor do que uma violação.
Registre o corpo completo do erro - status, cabeçalhos e payload - em toda chamada com falha, em todos os ambientes. Você vai precisar disso, e é muito mais difícil reconstruir depois.
#O que cada status costuma significar
| Status | Causa habitual |
|---|---|
| 400 | Uma requisição malformada - um campo obrigatório ausente, um valor de enum inválido, um objeto aninhado com formato errado |
| 401 | A autenticação falhou. O cabeçalho x-api-key está ausente, malformado ou não é uma chave válida |
| 403 | Autenticado, mas não permitido. Ambiente errado, uma permissão que sua chave não tem, ou um recurso não habilitado na sua conta |
| 404 | O recurso não existe - ou existe em uma aplicação diferente daquela da chave usada |
| 409 | Um conflito com o estado existente, como uma ação que já foi realizada |
| 422 | A requisição estava bem formada, mas os valores não são aceitáveis - uma falha de validação, não de sintaxe |
| 429 | Limite de taxa atingido. Veja abaixo |
| 5xx | Um problema do lado da Didit. Tente novamente com backoff e verifique status.didit.me |
#401 vs 403 - a distinção que economiza tempo
401 significa que a chave não foi aceita de forma alguma. Verifique se você está enviando x-api-key, se o valor não tem espaços em branco ou aspas indevidas, e se você não colou um signing secret de webhook no lugar da chave de API - são coisas diferentes e esse erro é comum.
403 significa que a chave é válida, mas essa chamada não é permitida. Três causas, em ordem:
- Incompatibilidade de ambiente. Campos exclusivos de sandbox (como
sandbox_scenario) são rejeitados em uma aplicação em produção, e vice-versa. Produção e sandbox são aplicações separadas, com chaves separadas. - Permissão ausente. Algumas operações exigem permissões que sua chave ou função não possui. Se você precisa de direitos de criação e gerenciamento de sessão que não tem, isso é uma solicitação ao suporte, não um ajuste de código.
- Recurso não habilitado. Algumas capacidades são provisionadas por organização. Um 403 em um recurso que você acredita que deveria ter vale a pena ser questionado antes de reescrever a chamada.
Não existe uma forma nativa de diferenciar uma chave de sandbox de uma chave de produção só de olhar para ela, então guarde-as com nomes claramente distintos no seu gerenciador de secrets e nunca deixe que uma única variável de ambiente contenha "seja qual for a chave atual". Uma chave de produção em um ambiente de teste gasta créditos reais.
#404 que deveria existir
Se uma sessão ou fluxo de trabalho retorna 404 e você tem certeza de que existe, a explicação costuma ser que ele existe em uma aplicação diferente daquela da chave com a qual você se autenticou. Os recursos são vinculados à sua aplicação; uma chave da aplicação A não consegue ver as sessões da aplicação B.
#Erros de saldo e crédito
Uma chamada que falha por falta de créditos suficientes não é um problema de código. O fluxo de trabalho contém um recurso pago e seu saldo não cobre isso. Esse é, de longe, o relato mais comum de "a API quebrou", e a causa quase sempre é white label, AML ou NFC em um fluxo de trabalho que se esperava que fosse gratuito. Veja como corrigir um erro de "créditos insuficientes".
#Limite de taxa 429
Os limites são aplicados por identificador - sua x-api-key, ou o IP do seu cliente se nenhuma chave for enviada - com um contador independente por escopo em uma janela deslizante de 60 segundos.
Padrões globais:
| Escopo | Métodos | Limite |
|---|---|---|
| Leituras genéricas | GET | 600 / min |
| Escritas genéricas | POST, PATCH, DELETE | 300 / min |
Alguns endpoints de alto impacto têm limites mais rígidos além do limite global, e o primeiro escopo a ultrapassar seu contador é o que retorna 429. Tabela completa: limite de taxa.
Trate o 429 com backoff exponencial e jitter. Um loop de novas tentativas muito frequente contra um limite de taxa piora o problema e pode manter você limitado indefinidamente.
Jobs em lote costumam ser a origem de um 429 - uma importação noturna que dispara várias centenas de criações em poucos segundos. Distribua o trabalho em vez de aumentar a concorrência até o erro parar.
#Códigos de detalhe em nível de recurso
Além dos status HTTP, cada verificação individual retorna seus próprios códigos de detalhe para problemas em nível de provedor - por exemplo, uma integração de registro que não tem acesso a um determinado produto em um determinado país. Quando você receber um desses, o código descreve a situação com precisão, então cite-o ao perguntar sobre ele.
Se uma resposta omitir um código de detalhe que você esperaria ver no catálogo, vale a pena reportar isso em vez de contornar - um código ausente é uma lacuna real, e torna o mesmo problema mais difícil para a próxima pessoa.
#Respostas vazias não são sucesso
Uma verificação apoiada em um provedor que retorna um corpo vazio não é o mesmo que um resultado limpo. Trate "sem dados" como um caso próprio no seu código, em vez de mapeá-lo como aprovado - principalmente para validação de banco de dados e triagem de carteiras, onde um serviço não provisionado e uma ausência de correspondência genuína podem parecer iguais vistos de fora.
#Testando caminhos de erro
O sandbox força falhas específicas de forma determinística, o que é a única maneira sensata de testar o tratamento de erros do seu sistema. Veja testes no sandbox.