Sol·licituds idempotents

Una sol·licitud pot fallar quan Sursa ja ha fet la feina: la connexió es talla, o el vostre procés es reinicia abans que arribi la resposta. Si torneu a enviar el mateix POST, podríeu crear una segona entrada o un segon webhook. Una clau d’idempotència ho evita.

Envieu una capçalera Idempotency-Key amb cada POST i PATCH. Si Sursa ja ha vist una sol·licitud amb aquesta clau, no torna a executar l’operació: retorna la resposta que va desar la primera vegada.

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."}'

Una sol·licitud repetida rep el mateix estat i el mateix cos que la primera, amb una capçalera addicional:

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

La sol·licitud repetida té el seu propi X-Request-Id.

Triar una clau

Feu servir un valor aleatori nou, com ara un UUID v4, per a cada operació lògica: «crear aquesta entrada», «registrar aquest webhook». Feu servir el mateix valor en tots els reintents d’aquella operació, i mai en una altra.
Una bona clau es deriva de les vostres pròpies dades quan en teniu, per exemple sync-2026-10-24-record-1042. Així, fins i tot un treball reiniciat que ha perdut la memòria torna a enviar la mateixa clau.
La clau té d’1 a 255 caràcters ASCII imprimibles. Qualsevol altra cosa retorna 400 amb el codi api.idempotency_key_invalid.

Què fa Sursa amb la clau

Situació	Resposta
Primera sol·licitud amb aquesta clau	L’operació s’executa com sempre.
Mateixa clau, mateixa sol·licitud, la primera ha acabat amb `2xx` o `4xx`	La resposta desada, amb `Idempotency-Replayed: true`. L’operació no es torna a executar.
Mateixa clau, la primera sol·licitud encara s’està executant	`409` `api.idempotency_in_progress` amb `Retry-After: 1`. Espereu i torneu-ho a provar.
Mateixa clau, però un mètode, un camí, un `Content-Type` o un cos diferents	`409` `api.idempotency_mismatch`. La clau ja la fa servir una altra sol·licitud.
La primera sol·licitud ha acabat amb `5xx` o `429`	La clau s’allibera: la sol·licitud següent que la porti torna a executar l’operació.

Una clau és vàlida durant 24 hores. Després, la mateixa clau inicia una operació nova.
Les claus són independents per a cada organització i per a cada qui fa la crida: dues claus d’API diferents poden fer servir el mateix valor sense afectar-se.
També es desa una resposta d’error amb 4xx. Una sol·licitud que no ha superat la validació falla de la mateixa manera quan es repeteix amb la mateixa clau; corregiu-la i envieu-la amb una clau nova.

Quines sol·licituds la necessiten

Mètode	Idempotency-Key
`POST`, `PATCH`	Envieu-la. Cada punt final que desa la resposta per a una repetició indica la capçalera a la referència de l’API.
`GET`, `PUT`, `DELETE`	No cal: pel seu significat, aquests mètodes es poden repetir sense risc. La capçalera s’accepta i no té cap efecte.
`POST` que només llegeix, com ara la cerca, els informes financers i `POST /v1/catalog/resolve`	S’accepta, però no es desa res: la sol·licitud simplement es torna a executar.

Algunes operacions es poden repetir sense risc fins i tot sense la capçalera:

PUT /v1/cards-by-external-id/{external_id} crea o substitueix l’entrada amb el vostre ID; una repetició amb el mateix contingut no canvia res.
Els documents d’una font personalitzada s’identifiquen pel vostre external_id; si torneu a enviar el mateix document, la resposta és unchanged.
Una resposta de l’assistent que POST /v1/chat transmet en temps real fa servir el camp request_id del cos en lloc de la capçalera. Vegeu Crear un bot de preguntes i respostes.

Reintentar sense risc

Combineu la clau amb les regles de reintent d’Errors: creeu la clau una sola vegada, abans del primer intent, i envieu-la amb cada intent de la mateixa operació.