Ir para o conteúdo
Docs

Idempotência

Como o cabeçalho Idempotency-Key evita cobranças e saques duplicados em novas tentativas.

Como funciona

POST /v1/charges e POST /v1/payouts exigem o cabeçalho Idempotency-Key, com 8 a 120 caracteres. Sem ele, a API responde 400 idempotency_key_required.

A chave fica ligada para sempre ao recurso criado, dentro da sua empresa e do tipo de recurso. Repetir a chamada com a mesma chave e o mesmo corpo devolve o mesmo recurso, com 201 e o cabeçalho Idempotent-Replayed: true. A resposta mostra o estado atual: se a cobrança já foi paga, vem paid.

Duas chamadas simultâneas com a mesma chave também resultam em um recurso só.

Segunda chamada com a mesma chaveHTTP
POST /v1/charges
Idempotency-Key: pedido-1042

HTTP/1.1 201 Created
Idempotent-Replayed: true

{
  "id": "6f0c1a52-1d7e-4b8a-9f43-2c5e8d9b7a10",
  "status": "paid",
  "...": "o estado atual da mesma cobrança"
}

Mesma chave, outro conteúdo

Reusar a chave com outro conteúdo responde 409 idempotency_conflict e nada é criado. A comparação usa o corpo depois da validação: a ordem dos campos não importa e espaços nas pontas dos textos são ignorados.

RespostaJSON409 Conflict
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Esta Idempotency-Key já foi usada com outro conteúdo. Gere uma chave nova para uma operação nova.",
    "requestId": "req_7nA0ZiWxZXgM1u8p"
  }
}

Boas práticas

  • Use um identificador da operação no seu sistema, como o número do pedido, ou um UUID gravado antes da chamada.
  • Em timeout, erro de rede, 429 ou 500, repita com a mesma chave. Você recebe o recurso que já existe ou o cria pela primeira vez.
  • Erros de validação e de permissão, como 422 invalid_body e 403 account_not_verified, não consomem a chave: corrija e envie de novo.
  • Depois de 502 processing_failed ou 422 insufficient_balance, a chave fica ligada ao registro com falha. Para tentar de novo, gere uma chave nova.
esc