Skip to content

Safe retries

A network can fail after we saved your request but before you got the answer. If you send the request again, you should not create everything twice. The Idempotency-Key header solves this.

The two import routes need it: POST /external/v1/guest-list-import and POST /external/v1/concierge-entry-import.

How to use it

  1. Make a new UUID v4 for each batch you mean to send.
  2. Store it with the batch, before you send.
  3. Send it in the Idempotency-Key header.
  4. If you do not get a clear answer, send the same batch again with the same key.
curl -X POST "https://production.speakeasygo.com/external/v1/concierge-entry-import" \
  -H "token: $SPEAKEASY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a54-7b1e-4a53-9f55-1c6a0e8b2d11" \
  -d '[{"venueId": "11111111-1111-4111-8111-111111111111", "phoneNumber": "+13125551212", "conversationSummary": "Birthday table for 6 on Saturday."}]'

What you get back

Case Answer
A new key The batch is saved, 201
The same key and the same request, and the first one finished The first answer again, with the same ids and time. Nothing new is created.
The same key and the same request, still running 409 with code IDEMPOTENCY_REQUEST_IN_PROGRESS. Wait, and try again with the same key.
The same key and a different request 409 with code IDEMPOTENCY_KEY_REUSED
Your integration's settings changed during the request 409 with code EXTERNAL_API_PROVISIONING_CHANGED. Try again with the same key.

A missing key gets a 400 with IDEMPOTENCY_KEY_REQUIRED, and a key that is not a UUID v4 gets a 400 with IDEMPOTENCY_KEY_INVALID.

Good to know

  • A key belongs to your integration, across all routes.
  • The same request means the same route, the same order of entries and the same values.
  • We check your key and access again on every retry. A retry can get a 403 or 404 if your access changed since the first try.
  • Validation errors are not stored. Fix the request and send it again. Use the same key if the batch still means the same thing.
  • Use a new key for a new batch. If you are not sure the first try went through, retry with the old key first. A new key can create duplicates.