# Erros da API e o que eles significam

Source: https://help.didit.me/pt-BR/integration/api-errors
Updated: 2026-10-12

Leia o corpo do erro antes do status: 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 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.

![A página de chaves de API no console da Didit, mostrando o status da chave e o último uso](https://help.didit.me/screenshots/api-keys-light.webp)

*A maioria dos 401 e 403 é respondida nesta página.*

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](https://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:

1. **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.
2. **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.
3. **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.

> **Tip:** 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 crédito do plano e o saldo não cobrem uma verificação do fluxo de trabalho. 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 custasse menos. Veja [como corrigir um erro de "créditos insuficientes"](https://help.didit.me/pt-BR/billing-credits/not-enough-credits).

## 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](https://docs.didit.me/integration/rate-limiting).

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.

> **Note:** 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](https://help.didit.me/pt-BR/getting-started/sandbox-and-testing).