# Erros da API e o que significam

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

O que cada estado HTTP da API da Didit costuma significar - 401 e 403 em chaves e permissões, 402 de saldo, 429 de limite de taxa, 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.

![A página de chaves de API na consola Didit, a mostrar o estado da chave e a última utilização](https://help.didit.me/screenshots/api-keys-light.webp)

*A maioria dos 401 e 403 tem resposta nesta página.*

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

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

> **Tip:** 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, ou o crédito do plano e o saldo já esgotados. Consulta [corrigir um erro de "créditos insuficientes"](https://help.didit.me/pt-PT/billing-credits/not-enough-credits).

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

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.

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