Idempotência

Idempotência

Header Idempotency-Key em todos os POST. Janela de 5 min, replay e conflitos em voo.

Aplica-se a todos os POST do escopo /v1 quando o header é enviado.

ItemValor
HeaderIdempotency-Key: <string única> (opcional, recomendado)
EscopoPor API key + por chave de idempotência
Janela “em processamento”5 minutos

Comportamento

  • Primeira request com a chave: processa normalmente e persiste a resposta.
  • Repetição após concluída: retorna a resposta original + header Idempotent-Replayed: true.
  • Repetição enquanto processa (< 5 min): retorna 409:
{ "error": "Requisição com esta Idempotency-Key em processamento", "code": "IDEMPOTENCY_IN_FLIGHT" }

Falhas transitórias (5xx, 429, ou os 409 META_RATE_LIMIT / TIER_DAILY_CAP_REACHED / ACCOUNT_TOKEN_INVALID / WINDOW_CLOSED) não consomem a chave — você pode reenviar com a mesma Idempotency-Key. Resultados determinísticos (2xx e 4xx não-transitórios) são persistidos para replay.

HTTP code Quando
409 IDEMPOTENCY_IN_FLIGHT POST com a mesma Idempotency-Key ainda processando
Pular para o conteúdo