Limite de pedidos da API: Limites, Cabeçalhos e Erro 429

​

Identificador e exceções

1. Cabeçalho x-api-key → contador por chave.
2. Primeiro salto de X-Forwarded-For → contador por IP.
3. REMOTE_ADDR → contador por IP.

• A DIDIT_WEBAPP_API_KEY interna (usada apenas pela consola do Didit).
• Endpoints protegidos pela permissão IsValidSession (tráfego de sessões incorporadas e do SDK).
• GET /system/healthcheck (servido pelo HealthMiddleware antes desta pilha).
• Webhooks de fornecedores: Stripe, triagem AML, retornos de chamada de verificação facial e alterações a listas KYC.

​

Limites globais

​

Limites específicos de endpoints

​

Formato da resposta 429

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1762534870
Retry-After: 37

{
  "detail": "Session creation rate limit exceeded. You can make up to 600 requests per minute."
}

​

Orientações para clientes

• Respeite Retry-After como o mínimo do seu tempo de espera. Sobre esse mínimo, aplique um backoff exponencial com variação aleatória (jitter) (5s → 10s → 20s → 40s ± random), para que dois clientes que recebam 429 ao mesmo tempo não se sincronizem.
• Deixe de tentar novamente após um limite reduzido (por exemplo, 5 tentativas). Devolva o erro ao seu chamador e alerte a sua equipa: respostas 429 persistentes costumam indicar um ciclo descontrolado, e não um pico pontual.
• Use um identificador por carga de trabalho. Partilhar um x-api-key entre vários backends junta-os no mesmo contador, o que pode fazer com que um vizinho ruidoso deixe os restantes sem recursos. Crie uma aplicação separada (e, por conseguinte, um api_key separado) por ambiente, marca ou cliente; veja Registo programático.
• Guarde em cache as leituras de decisão. Os endpoints /decision/ não foram concebidos para ciclos de polling apertados. Se precisar de atualizações em tempo real, use Webhooks e chame GET /v3/session/<id>/decision/ apenas para preenchimento retroativo ou auditoria.
• Gere os PDF offline. A geração de PDF está limitada pela CPU (limite de 50/min). Acione-a a partir de uma fila depois de a sessão atingir um estado final, e não em cada visualização de página.

​

Cliente de exemplo com tratamento de 429

async function postSession(body) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch("https://verification.didit.me/v3/session/", {
      method: "POST",
      headers: {
        "x-api-key": process.env.DIDIT_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });

    if (res.status !== 429) return res;

    const retryAfter = Number(res.headers.get("Retry-After") ?? "1");
    const jitter = Math.random() * 1000;
    await new Promise((r) => setTimeout(r, retryAfter * 1000 + jitter));
  }
  throw new Error("Didit: too many 429s, giving up");
}

import os
import random
import time

import httpx

def post_session(body: dict) -> httpx.Response:
    with httpx.Client(timeout=15) as client:
        for _ in range(5):
            resp = client.post(
                "https://verification.didit.me/v3/session/",
                headers={
                    "x-api-key": os.environ["DIDIT_API_KEY"],
                    "Content-Type": "application/json",
                },
                json=body,
            )
            if resp.status_code != 429:
                return resp
            wait_s = float(resp.headers.get("Retry-After", "1")) + random.random()
            time.sleep(wait_s)
    raise RuntimeError("Didit: too many 429s, giving up")

​

Precisa de mais capacidade?