Requisições idempotentes

Uma requisição pode falhar depois que o Sursa já fez o trabalho: a conexão cai ou o seu processo reinicia antes de a resposta chegar. Se você enviar o mesmo POST de novo, pode criar um segundo cartão ou um segundo webhook. Uma chave de idempotência evita isso.

Envie um cabeçalho Idempotency-Key em cada POST e PATCH. Se o Sursa já recebeu uma requisição com essa chave, ele não executa a operação de novo: retorna a resposta que salvou da primeira vez.

curl -X POST https://api.sursa.com/v1/cards/text \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: 6f1d2c9e-7b0a-4c43-9a51-0d6c1c1f8e21" \
  -H "Content-Type: application/json" \
  -d '{"title": "Refund policy", "body_markdown": "Refunds are processed within 14 days."}'

Uma requisição repetida recebe o mesmo status e o mesmo corpo que a primeira, com um cabeçalho a mais:

HTTP/1.1 200 OK
Idempotency-Replayed: true
X-Request-Id: 01JB7R…

A requisição repetida tem o próprio X-Request-Id.

Escolha da chave

Use um novo valor aleatório, como um UUID v4, para cada operação lógica: “criar este cartão”, “registrar este webhook”. Use o mesmo valor em todas as novas tentativas dessa operação e nunca em uma operação diferente.
Uma boa chave é derivada dos seus próprios dados, quando você os tem, por exemplo sync-2026-10-24-record-1042. Assim, até um job reiniciado que perdeu a memória envia a mesma chave de novo.
A chave tem de 1 a 255 caracteres ASCII imprimíveis. Qualquer outra coisa retorna 400 com o código api.idempotency_key_invalid.

O que o Sursa faz com a chave

Situação	Resposta
Primeira requisição com esta chave	A operação é executada normalmente.
Mesma chave, mesma requisição, a primeira terminou com `2xx` ou `4xx`	A resposta salva, com `Idempotency-Replayed: true`. A operação não é executada de novo.
Mesma chave, a primeira requisição ainda está em execução	`409` `api.idempotency_in_progress` com `Retry-After: 1`. Aguarde e tente de novo.
Mesma chave, com outro método, caminho, `Content-Type` ou corpo	`409` `api.idempotency_mismatch`. A chave já está ocupada por outra requisição.
A primeira requisição terminou com `5xx` ou `429`	A chave é liberada: a próxima requisição com ela executa a operação de novo.

Uma chave vale por 24 horas. Depois disso, a mesma chave inicia uma nova operação.
As chaves são separadas por organização e por quem faz a chamada: duas chaves de API diferentes podem usar o mesmo valor sem interferir uma na outra.
Uma resposta de erro com 4xx também é salva. Uma requisição que falhou na validação falha da mesma forma quando é repetida com a mesma chave; corrija-a e envie-a com uma chave nova.

Quais requisições precisam dela

Método	Idempotency-Key
`POST`, `PATCH`	Envie. Todo endpoint que guarda a resposta para uma repetição lista o cabeçalho na referência da API.
`GET`, `PUT`, `DELETE`	Não é necessária: pelo próprio significado, esses métodos podem ser repetidos com segurança. O cabeçalho é aceito e não tem efeito.
`POST` que só lê, como a busca, os relatórios financeiros e `POST /v1/catalog/resolve`	Aceita, mas nada é salvo: a requisição simplesmente é executada de novo.

Algumas operações podem ser repetidas com segurança mesmo sem o cabeçalho:

PUT /v1/cards-by-external-id/{external_id} cria ou substitui o cartão com o seu ID; uma repetição com o mesmo conteúdo não altera nada.
Os documentos de uma fonte personalizada são identificados pelo seu external_id; enviar o mesmo documento de novo retorna unchanged.
Uma resposta transmitida de POST /v1/chat usa o campo request_id do corpo em vez do cabeçalho. Veja Criar um bot de perguntas e respostas.

Novas tentativas seguras

Combine a chave com as regras de novas tentativas de Erros: crie a chave uma vez, antes da primeira tentativa, e envie-a em todas as tentativas da mesma operação.