Idempotentit pyynnöt

Pyyntö voi epäonnistua, vaikka Sursa on jo tehnyt työn: yhteys katkeaa tai prosessisi käynnistyy uudelleen ennen kuin vastaus saapuu. Jos lähetät saman POST-pyynnön uudelleen, saatat luoda toisen kortin tai toisen webhookin. Idempotenssiavain estää tämän: saman pyynnön toisto ei suorita toimintoa uudelleen.

Lähetä Idempotency-Key-otsake jokaisen POST- ja PATCH-pyynnön mukana. Jos Sursa on jo nähnyt pyynnön, jossa on tämä avain, se ei suorita toimintoa uudelleen vaan palauttaa vastauksen, jonka se tallensi ensimmäisellä kerralla.

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

Toistettu pyyntö saa saman tilan ja rungon kuin ensimmäinen, ja siinä on yksi lisäotsake:

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

Toistetulla pyynnöllä on oma X-Request-Id.

Avaimen valinta

Käytä jokaiselle loogiselle toiminnolle uutta satunnaista arvoa, kuten UUID v4: ”luo tämä kortti”, ”rekisteröi tämä webhook”. Käytä samaa arvoa toiminnon jokaisessa uusintayrityksessä äläkä koskaan millekään muulle toiminnolle.
Hyvä avain johdetaan omista tiedoistasi, jos sellaiset on, esimerkiksi sync-2026-10-24-record-1042. Silloin jopa uudelleen käynnistetty työ, joka on menettänyt muistinsa, lähettää saman avaimen uudelleen.
Avaimessa on 1–255 tulostettavaa ASCII-merkkiä. Kaikki muu palauttaa 400-vastauksen ja koodin api.idempotency_key_invalid.

Mitä Sursa tekee avaimella

Tilanne	Vastaus
Ensimmäinen pyyntö tällä avaimella	Toiminto suoritetaan tavalliseen tapaan.
Sama avain, sama pyyntö, ensimmäinen päättyi tilaan `2xx` tai `4xx`	Tallennettu vastaus otsakkeella `Idempotency-Replayed: true`. Toimintoa ei suoriteta uudelleen.
Sama avain, ensimmäinen pyyntö on vielä käynnissä	`409` `api.idempotency_in_progress` ja `Retry-After: 1`. Odota ja yritä uudelleen.
Sama avain, eri metodi, polku, `Content-Type` tai runko	`409` `api.idempotency_mismatch`. Avain on jo toisen pyynnön käytössä.
Ensimmäinen pyyntö päättyi tilaan `5xx` tai `429`	Avain vapautetaan: seuraava pyyntö samalla avaimella suorittaa toiminnon uudelleen.

Avain on voimassa 24 tuntia. Sen jälkeen sama avain aloittaa uuden toiminnon.
Avaimet ovat erilliset kullekin organisaatiolle ja kutsujalle: kaksi eri API-avainta voi käyttää samaa arvoa vaikuttamatta toisiinsa.
Myös 4xx-virhevastaus tallennetaan. Validoinnissa epäonnistunut pyyntö epäonnistuu samalla tavalla, kun se toistetaan samalla avaimella; korjaa pyyntö ja lähetä se uudella avaimella.

Mitkä pyynnöt tarvitsevat avaimen

Metodi	Idempotency-Key
`POST`, `PATCH`	Lähetä se. API-viitteessä tämä otsake mainitaan jokaisen sellaisen päätepisteen kohdalla, joka tallentaa vastauksensa toistoa varten.
`GET`, `PUT`, `DELETE`	Ei tarvita: nämä metodit ovat luonteensa vuoksi turvallisia toistaa. Otsake hyväksytään, eikä sillä ole vaikutusta.
Vain lukeva `POST`, kuten haku, talousraportit ja `POST /v1/catalog/resolve`	Hyväksytään, mutta mitään ei tallenneta: pyyntö yksinkertaisesti suoritetaan uudelleen.

Jotkin toiminnot ovat turvallisia toistaa ilman otsakettakin:

PUT /v1/cards-by-external-id/{external_id} luo tai korvaa kortin, jolla on sinun tunnuksesi; toisto samalla sisällöllä ei muuta mitään.
Mukautetun lähteen asiakirjat yksilöidään omalla external_id-tunnuksellasi; saman asiakirjan lähettäminen uudelleen palauttaa unchanged.
POST /v1/chat -pyynnön virtana tuleva vastaus käyttää otsakkeen sijaan rungon request_id-kenttää. Ks. Kysymys–vastaus-botin rakentaminen.

Turvalliset uusintayritykset

Yhdistä avain oppaan Virheet uusintayrityssääntöihin: luo avain kerran ennen ensimmäistä yritystä ja lähetä se saman toiminnon jokaisen yrityksen mukana.