PT EN

Idempotência

Repita um POST após uma falha de rede sem criar registos duplicados, com o cabeçalho Idempotency-Key, e saiba quando a resposta guardada é devolvida e quando há conflito.

Quando um POST fica sem resposta (tempo esgotado, ligação cortada), não sabe se o servidor chegou a executá-lo. Se o pedido levar o cabeçalho Idempotency-Key, pode repeti-lo com a mesma chave: o servidor executa-o uma vez e, nas repetições, devolve a resposta que guardou.

Onde funciona#

O cabeçalho é aceite em todos os pedidos POST da Business API ($BUSINESS_API) e da Consumer API ($CONSUMER_API), tanto em criações como em acções sobre um registo existente. Os pedidos GET, PATCH, PUT e DELETE ignoram-no. Sem o cabeçalho, o pedido é executado normalmente, sem protecção contra repetições.

Regras da chave#

  • De 1 a 255 caracteres ASCII visíveis, sem espaços. Um UUID v4 gerado pelo seu sistema por cada operação lógica serve bem.
  • Uma chave fora deste formato é recusada com 400 e invalid_params a apontar para Idempotency-Key.
  • A chave vale para a combinação de credencial (Authorization), contexto (X-Context-ID), método e caminho. A mesma chave enviada com outra chave de API ou para outro caminho é tratada como nova.
  • A resposta guardada fica disponível durante 24 horas após o primeiro pedido.

Exemplo de pedido e resposta#

Este pedido cria um cliente e precisa da permissão business:customers:create.

bash
curl -sS -X POST "$BUSINESS_API/customers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: 9b2f4c1e-7a3d-4e8b-b5c6-0d1e2f3a4b5c" \
  -H "Content-Type: application/json" \
  -d '{"customer_type":"individual","category":"residential","display_name":"Felismina Mabunda","phone":"+258849876543"}'

Primeira resposta, 201 Created:

json
{
  "id": "cus_2kGa3TnW7qLzE5rHbV1mXc8yJdP",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "customer_type": "individual",
  "category": "residential",
  "display_name": "Felismina Mabunda",
  "phone": "+258849876543",
  "status": "active",
  "created_at": "2026-11-19T10:42:07.318250Z",
  "updated_at": "2026-11-19T10:42:07.318250Z"
}

Se repetir exactamente o mesmo pedido, recebe outra vez 201 com o mesmo id, mais dois cabeçalhos: Idempotency-Key com a chave enviada e Idempotent-Replayed: true, que indica que esta é a resposta guardada e não uma segunda execução.

Conflito: a mesma chave com outro corpo#

O servidor compara o corpo de cada repetição com o do primeiro pedido. Se mudar um único campo e reutilizar a chave, recebe 409:

json
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "Idempotency-Key was already used with a different request payload.",
  "instance": "$BUSINESS_API/customers",
  "code": "CONFLICT",
  "error_code": "request.idempotency_conflict",
  "request_id": "req_4f1c9a2b7e3d48a6b0c5d2e1f9a8b7c6"
}

Gere uma chave nova sempre que o conteúdo do pedido muda. O campo type aponta para a página de erros do site quando o operador o configura; caso contrário vem como about:blank.

O que fica guardado#

  • Respostas com estado abaixo de 500 ficam guardadas, incluindo recusas 4xx. Se o primeiro pedido falhou por um campo inválido, a repetição com a mesma chave devolve a mesma recusa: corrija o corpo e use uma chave nova.
  • Erros 5xx não ficam guardados. Pode repetir com a mesma chave e o pedido volta a ser executado.
  • Corpos de pedido acima de 4 MiB não passam pela protecção de idempotência.
  • As chaves vivem na memória do servidor que respondeu. Uma repetição atendida por outra instância, ou depois de um reinício, é executada de novo.
  • Alguns endpoints também registam a chave na base de dados. Os comandos de turno de caixa guardam-na durante 7 dias, por isso aí a repetição é reconhecida mesmo depois de um reinício; a operação respectiva na referência explica o funcionamento.

Próximos passos#