Idempotência

Um pedido de escrita que expira deixa-o sem saber o que aconteceu: o pedido chegou e foi executado, e só a resposta é que se perdeu? Ou não chegou de todo? Repetir arrisca duplicar; não repetir arrisca perder.

A chave de idempotência resolve isso. Envie-a no cabeçalho Idempotency-Key:

curl -X POST "https://servidor.exemplo/api/integrations/v1/acme/occurrences" \
  -H "ApiKey: $GC_API_KEY" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Content-Type: application/json" \
  -d '{ "IdBuilding": 12, "Description": "Infiltração na garagem" }'

Se repetir o pedido com a mesma chave, a API não executa nada de novo: devolve exatamente a resposta que a primeira tentativa produziu, com o mesmo estado HTTP e o mesmo corpo. Do seu lado é indistinguível de ter corrido bem à primeira — que é o objetivo.

Como gerar a chave

Um UUID por operação de negócio. Gere-o antes do primeiro envio e reutilize-o em todas as repetições dessa mesma operação.

const idempotencyKey = crypto.randomUUID()

async function createOccurrence(body)
{
    //every retry of THIS occurrence reuses the same key
    return await post('/occurrences', body, idempotencyKey)
}

Não gere uma chave nova a cada tentativa

É o erro que anula o mecanismo por completo: com chave nova, cada repetição é uma operação nova, e acaba com cinco ocorrências iguais abertas. A chave identifica a intenção, não a tentativa.

Onde se aplica

Operação	Caminho
Abrir ocorrência	POST /occurrences
Abrir sinistro	POST /claims
Atribuir ocorrência	POST /occurrences/{id}/assignment
Registar intervenção	POST /occurrences/{id}/interventions
Alterar estado ou prioridade	PATCH /occurrences/{id}
Registar fatura de fornecedor	POST /supplier-invoices
Registar fatura de consumo	POST /supplier-invoices/consumption
Registar pagamento	POST /supplier-payments
Registar pagamento de consumo	POST /supplier-payments/consumption
Registar despesa	POST /expenses
Enviar mensagem	POST /emails
Submeter proposta	POST /proposals
Criar marcação	POST /calendar-entries
Alterar marcação	PATCH /calendar-entries/{id}
Apagar marcação	DELETE /calendar-entries/{id}

Ou seja: todas as operações de escrita.

O cabeçalho é opcional. Sem ele, cada pedido é executado como pedido novo — o que para um sistema não assistido raramente é o que quer.

Nas despesas, a chave é a única proteção

As faturas de fornecedor têm uma segunda proteção: o mesmo número de documento do mesmo fornecedor é recusado com 409 DOCUMENT_ALREADY_EXISTS. As despesas não têm nenhuma equivalente. Um POST /expenses repetido sem a mesma chave fica lançado duas vezes na contabilidade do condomínio, e só um utilizador da aplicação o pode desfazer.

Operações que não devolvem corpo

Apagar ou alterar uma marcação responde 204 sem corpo. A repetição com a mesma chave devolve o mesmo 204, também sem corpo.

Repare no que isto evita: sem a chave, repetir uma eliminação responde 404 ENTRY_NOT_FOUND — que se lê como falha, quando na verdade a marcação está exatamente como queria. Com a chave, a repetição confirma o que a primeira tentativa fez.

Reutilizar a chave noutro pedido

Uma chave já usada, apresentada num pedido com método ou caminho diferentes, responde 409:

{
  "Error": {
    "Code": "IDEMPOTENCY_KEY_REUSED",
    "Message": "This Idempotency-Key was already used on a different request. Use a new one.",
    "Field": "Idempotency-Key"
  }
}

É uma proteção contra um erro de programação: se a API repetisse a resposta antiga, ficaria a acreditar que criou algo que na verdade não criou.

Só o método e o caminho são comparados

O corpo do pedido não entra na comparação. Repetir a mesma chave no mesmo caminho com um corpo diferente devolve a resposta original e o segundo corpo é ignorado — em silêncio. Uma chave por operação, sempre.

Durante quanto tempo

24 horas. Passado esse prazo, uma repetição da mesma chave é tratada como operação nova e executada.

O prazo é largo para qualquer política de repetição razoável, e curto o suficiente para que uma chave reaproveitada semanas depois — por exemplo, derivada de um identificador do seu lado — não devolva um resultado antigo que já nada tem a ver.

Não derive a chave de dados de negócio

Chaves como fatura-2026-0012 parecem convenientes mas colidem entre si, atravessam o prazo de retenção e, quando a operação legítima se repete meses depois, respondem com o resultado antigo. Use identificadores aleatórios.

Âmbito

A chave é sua: duas credenciais diferentes podem usar a mesma sem interferirem uma com a outra.

O que fazer em cada caso

Situação	O que fazer
Tempo esgotado, sem resposta	Repita com a mesma chave
500 ou 502	Repita com a mesma chave, com espera crescente
429	Espere e repita com a mesma chave
400, 404 ou 422	Não repita: corrija o pedido e use uma chave nova
409 IDEMPOTENCY_KEY_REUSED	Erro seu: está a reutilizar a chave noutra operação