Erros da API e o que significam
O que cada estado HTTP da API da Didit costuma significar na prática - 401 e 403 em chaves e permissões, problemas de saldo do tipo 402, limites de taxa 429, e como ler o corpo do erro.
Lê o corpo da resposta. Os erros da Didit trazem uma mensagem e muitas vezes um código de detalhe que identifica o problema real - o estado por si só raramente chega. O 401 é a chave, o 403 é permissões ou ambiente, o 429 é limitação de taxa, e um erro de saldo é sobre créditos, não sobre código.
#Lê primeiro o corpo
O estado HTTP diz-te a categoria. O corpo diz-te o que aconteceu. Quase todas as horas de depuração evitáveis numa integração de API são gastas a adivinhar um código de estado, quando a resposta estava numa resposta que foi descartada.
- Uma chave desativada ou da aplicação errada é a causa habitual de um 401.
- Last used confirma se a chave que pensas estar a enviar é a que está a chegar.
- Roda o segredo se uma chave puder ter sido exposta - um 401 é melhor do que uma violação de segurança.
Regista o corpo completo do erro - estado, cabeçalhos e payload - em cada chamada falhada, em todos os ambientes. Vais precisar dele, e é muito mais difícil de reconstruir mais tarde.
#O que cada estado costuma significar
| Estado | Causa habitual |
|---|---|
| 400 | Um pedido mal formado - um campo obrigatório em falta, um valor de enum inválido, um objeto aninhado com a forma errada |
| 401 | Falha de autenticação. O cabeçalho x-api-key está em falta, mal formado, ou não é uma chave válida |
| 403 | Autenticado mas não permitido. Ambiente errado, uma permissão que a tua chave não tem, ou uma funcionalidade não ativada na tua conta |
| 404 | O recurso não existe - ou existe numa aplicação diferente da chave que usaste |
| 409 | Um conflito com o estado existente, como uma ação que já foi executada |
| 422 | O pedido estava bem formado mas os valores não são aceitáveis - uma falha de validação e não de sintaxe |
| 429 | Limitado por taxa. Ver abaixo |
| 5xx | Um problema do lado da Didit. Repete com backoff, e verifica status.didit.me |
#401 vs 403 - a distinção que poupa tempo
401 significa que a chave não foi aceite de todo. Confirma que estás a enviar x-api-key, que o valor não tem espaços ou aspas a mais, e que não colaste um segredo de assinatura de webhook em vez da chave de API - são coisas diferentes e o erro é comum.
403 significa que a chave é válida mas esta chamada não é permitida. Três causas, por ordem:
- Ambiente incompatível. Campos exclusivos de sandbox (como
sandbox_scenario) são rejeitados numa aplicação live, e vice-versa. Live e sandbox são aplicações separadas com chaves separadas. - Permissão em falta. Algumas operações precisam de permissões que a tua chave ou função não tem. Se precisares de direitos de criação e gestão de sessões que não tens, isso é um pedido ao suporte, não uma correção de código.
- Funcionalidade não ativada. Algumas capacidades são disponibilizadas por organização. Um 403 numa funcionalidade que acreditas que devias ter vale a pena perguntar antes de reescreveres a chamada.
Não há forma nativa de distinguir uma chave sandbox de uma chave live só de a ver, por isso guarda-as com nomes claramente distintos no teu gestor de segredos e nunca deixes uma única variável de ambiente conter "seja qual for a chave atual". Uma chave live num ambiente de teste gasta créditos reais.
#Um 404 que devia existir
Se uma sessão ou fluxo de trabalho devolve 404 e tens a certeza de que existe, a resposta habitual é que existe numa aplicação diferente da chave com que autenticaste. Os recursos estão limitados à 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éditos
Uma chamada que falha por não haver créditos suficientes não é um problema de código. O fluxo de trabalho contém uma funcionalidade paga e o teu saldo não a cobre. Este é, de longe, o relato mais comum de "a API avariou-se", e a causa é quase sempre white label, AML ou NFC num fluxo de trabalho que se esperava que fosse gratuito. Consulta corrigir um erro de "créditos insuficientes".
#Limitação de taxa 429
Os limites são aplicados por identificador - a tua x-api-key, ou o IP do teu cliente se não for enviada nenhuma chave - com um contador independente por âmbito numa janela deslizante de 60 segundos.
Valores predefinidos globais:
| Âmbito | 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 restritos além do limite global, e o primeiro âmbito a ultrapassar o seu contador é o que devolve 429. Tabela completa: limitação de taxa.
Trata o 429 com backoff exponencial e jitter. Um ciclo de repetição apertado contra um limite de taxa piora o problema e pode manter-te limitado indefinidamente.
Trabalhos em lote são a origem habitual de um 429 - uma importação noturna que dispara várias centenas de criações em poucos segundos. Distribui o trabalho no tempo em vez de aumentares a concorrência até parar de dar erro.
#Códigos de detalhe ao nível da funcionalidade
Além dos estados HTTP, cada comprovação devolve os seus próprios códigos de detalhe para problemas ao nível do fornecedor - por exemplo, uma integração de registo que não tem acesso a um determinado produto num determinado país. Quando recebes um, o código identifica a situação com precisão, por isso cita-o quando perguntares sobre ele.
Se uma resposta omitir um código de detalhe que esperarias do catálogo, vale a pena reportar em vez de contornar - um código em falta é uma lacuna real, e torna o mesmo problema mais difícil para a próxima pessoa.
#Respostas vazias não são sucesso
Uma comprovação apoiada num fornecedor que devolve um corpo vazio não é o mesmo que um resultado limpo. Trata "sem dados" como um caso próprio no teu código em vez de o mapeares como aprovação - particularmente na validação de base de dados e na cribagem de carteiras, onde um serviço não aprovisionado e uma ausência de correspondência genuína podem parecer iguais vistos de fora.
#Testar caminhos de erro
O sandbox força falhas específicas de forma determinística, que é a única forma sensata de testar o teu tratamento de erros. Consulta testar em sandbox.