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
400einvalid_paramsa apontar paraIdempotency-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.
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:
{
"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:
{
"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
5xxnã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.