Retries and idempotency

When a booking times out you can’t tell whether it worked. Retrying without protection risks two deliveries and two charges. The Idempotency-Key header removes that risk: send the same key again and you get the same answer, not a second job.

POST /v1/jobs requires the header. A booking without one is refused with request.missing_idempotency_key.

Choosing a key

Use something that identifies the booking in your own system — your order number is ideal:

Idempotency-Key: order-1042

The key belongs to your API key, so it can’t collide with anybody else’s. Use a new key for every new booking, and the same key for every retry of one booking.

What a repeat gets

You send	You get
The same key and the same body, after the first finished	Exactly the first response — same status code, same job.
The same key and the same body, while the first is still running	409 Conflict, request.in_progress. Wait a moment and retry.
The same key with a different body	422, request.idempotency_key_reused. Nothing is booked.

A refused booking is stored too: retrying a request that failed with quote.expired returns the same refusal. Fix the request and send it with a new key.

نکته

A safe retry loop: on a timeout, a connection error or a 5xx, wait and send the identical request with the identical key. On 409 request.in_progress, wait a little longer. On any other 4xx, stop and look at the error.