Idempotency - Smart Send

Idempotency er en ny funktion, der kun er tilgængelig i det kommende API, som i øjeblikket er i beta. Den beskrevne adfærd kan ændre sig, indtil API’et frigives i General Availability.

Netværksfejl, timeouts og andre forbigående fejl kan efterlade dig i tvivl om, hvorvidt en request rent faktisk nåede frem til Smart Send. Idempotency lader dig gentage sådanne requests sikkert, uden risiko for at booke den samme forsendelse to gange eller skabe dublerede ressourcer.

Sådan fungerer idempotency

Idempotency er opt-in. For at aktivere det skal du inkludere en Idempotency-Key-header på en write-request:

Example

Idempotency-Key: order-4521_9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Når API’et modtager en nøgle, det ikke har set før, behandler det requesten normalt og gemmer responsen sammen med nøglen. Hvis du gentager med samme nøgle og samme payload inden for 24 timer, returnerer API’et den gemte respons i stedet for at udføre handlingen igen. Gentagelsen er derfor sikker: en forsendelse bookes kun én gang, selv hvis du sender requesten to gange. Requests, der sendes uden en Idempotency-Key-header, bliver ikke deduplikeret. Hver enkelt behandles uafhængigt.

Idempotency gælder for write-operationer (POST og DELETE). Læseoperationer (GET) er allerede sikre at gentage, så de ignorerer headeren. Når en gemt respons gentages, inkluderer API’et en Idempotency-Replayed: true-responseheader, så du kan skelne en gentagelse fra en nyligt udført request.

Sådan opretter du en idempotency-nøgle

Nøglen er en streng, der entydigt identificerer en enkelt logisk handling. Den skal opfylde disse krav:

Krav	Værdi
Længde	16-128 tegn
Tilladte tegn	Bogstaver, tal, `.`, `_`, `-`
Versalfølsomhed	Versalfølsom (`ABC` og `abc` er forskellige nøgler)
Omfang	Unik pr. handling, pr. klient

En tilfældig UUID v4 fungerer, men den tvinger dig til at generere nøglen på forhånd og gemme den sammen med ordren, så du kan genbruge præcis den samme værdi ved en gentagelse. En enklere tilgang er at udlede nøglen deterministisk fra data, du allerede har, f.eks. ordre-id’et kombineret med request-payloaden. Fordi de samme input altid giver den samme nøgle, genberegner en gentagelse den identiske nøgle, uden at du behøver at gemme noget:

// $orderId er din egen ordrereference; $payload er den nøjagtige body, du vil sende.
$key = $orderId . '_' . hash('sha256', json_encode($payload));

// $key er din ordrereference efterfulgt af en 64-tegns hex-hash, f.eks.
// "order-4521_9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"

import { createHash } from 'node:crypto';

// orderId er din egen ordrereference; payload er den nøjagtige body, du vil sende.
const hash = createHash('sha256').update(JSON.stringify(payload)).digest('hex');
const key = `${orderId}_${hash}`;

Send den udledte værdi i Idempotency-Key-headeren. Hvis requesten fejler, og du gentager den, genberegner du nøglen ud fra den samme ordre og payload, og API’et genkender den som den samme handling.

At inkludere payloaden i nøglen betyder, at en anden payload giver en anden nøgle, som API’et behandler som en ny handling. Hvis du i stedet baserer nøglen på en stabil identifikator alene (f.eks. blot ordre-id’et), bliver genbrug med en ændret payload rapporteret som en konflikt — se nedenfor.

Sådan håndteres gentagne requests

Situation	Resultat
Ny nøgle	Requesten behandles normalt, og responsen gemmes.
Samme nøgle, samme payload, original færdig	Den gemte respons (statuskode og body) returneres, uden at handlingen udføres igen. Responsen indeholder headeren `Idempotency-Replayed: true`.
Samme nøgle, anden payload	`422 Unprocessable Entity`. Nøglen er allerede knyttet til en anden request.
Samme nøgle, original stadig i gang	`409 Conflict` med en `Retry-After`-header, der angiver, hvor mange sekunder du skal vente, før du prøver igen.

Nøgler er afgrænset pr. klient og udløber automatisk 24 timer efter første brug. Derefter kan den samme nøgle bruges igen til en ny handling.

En request, der fejler validering, gemmes ikke sammen med nøglen. Du kan rette payloaden og prøve igen med den samme nøgle.

Konflikter og fejl

Hvis du modtager en 409 Conflict, er den oprindelige request stadig under behandling. Vent det antal sekunder, der er angivet i Retry-After-responseheaderen, og prøv derefter igen med den samme nøgle:

Example response

HTTP/1.1 409 Conflict
Retry-After: 1

En 422 Unprocessable Entity betyder, at nøglen allerede er blevet brugt til en request med en anden payload. Genbrug enten den oprindelige payload, eller generér en ny nøgle til den nye handling.

​Sådan fungerer idempotency

​Sådan opretter du en idempotency-nøgle

​Sådan håndteres gentagne requests

​Konflikter og fejl

Sådan fungerer idempotency

Sådan opretter du en idempotency-nøgle

Sådan håndteres gentagne requests

Konflikter og fejl