Tirth API · Guide
Idempotency
A network can drop an answer after the work is done. An Idempotency-Key lets you send the same write again without doing it twice: the second time, you get the first answer back.
When to send one
| Write | Idempotency-Key |
|---|---|
POST /v2/bookings | Required |
POST /v2/bookings/{id}/amendments | Required |
POST /v2/bookings/{id}/cancellations | Required |
POST /v2/credit/top-ups | Required |
POST /v2/privacy-requests | Required |
POST /v2/quotes | Optional |
POST /v2/bookings/{id}/amendment-quotes | Optional |
POST /v2/webhook-endpoints and POST /v2/webhook-endpoints/{id}/rotate-secret | Optional |
POST /v2/sandbox/bookings/{id}/advance | Optional |
The key is a UUID v4, such as 6f1c2b7e-3a4d-4c5e-9f80-1a2b3c4d5e6f. A write that requires one and arrives without it, or with something else, is 400 idempotency_key_required, with field set to Idempotency-Key.
How it works
- Make a new key for each new write, and keep it with the write until you have its answer.
- Tirth keeps each key for 24 hours for your company, with the method, the path and a hash of the body. Both of your active secret keys share the same keys, so a retry after a key rotation still matches.
- Same key, same request: you get the first answer again, with its status, and the header
Idempotent-Replayed: true. Nothing is done twice. - Same key, different request:
409 idempotency_key_reused. Make a new key for a new request. - Same key while the first request is still being answered:
409 idempotency_in_progress. Wait a moment and send it again. - A refusal is kept like any other answer: a
402 credit_insufficientcomes back again for the same key. Once you have fixed the cause, such as adding credit, send the write with a new key. - An answer of
500or more keeps nothing, so a retry with the same key is safe.
A new webhook endpoint and a rotated secret answer with a signing secret that is shown once and never stored. Sending that request again with the same key is 409 conflict, not a replay: the secret is not shown a second time.
Retrying in Node
const wait = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));
async function bookOnce(body) {
const idempotencyKey = crypto.randomUUID();
for (let attempt = 1; ; attempt += 1) {
let response;
try {
response = await fetch('https://sandbox.api.tirth.com/v2/bookings', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.TIRTH_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': idempotencyKey,
},
body: JSON.stringify(body),
});
} catch (networkError) {
if (attempt === 5) throw networkError;
await wait(attempt);
continue;
}
const answer = await response.json();
if (response.ok) return answer;
const again = response.status >= 500 || answer.error.code === 'idempotency_in_progress';
if (!again || attempt === 5) throw new Error(`${answer.error.code} (request ${answer.error.request_id})`);
await wait(Number(response.headers.get('Retry-After') ?? attempt));
}
}The same idempotencyKey goes with every attempt: that is what makes the retry safe.
Your partner reference
Bookings also carry your own partner_reference, unique for your company forever. Even after an Idempotency-Key's 24 hours have passed, a booking with a reference you used before is 409 partner_reference_taken. Use one reference per order on your side, and look a booking up by it with GET /v2/bookings?partner_reference=….
