Made in 10Docs
GuidesAPI
Basics

Idempotency

Send an Idempotency-Key so that a retried request starts one call or one meeting, never two.

A network can drop the answer to a request that worked. Retrying it blindly could start a second call, and hold money for it. Send an Idempotency-Key header and a retry gives back the first call instead.

It works on the two requests that start something:

POST/v1/calls
POST/v1/meetings

How to use it

Make one key per call you mean to start, such as a UUID, and send the same key on every retry of that request.

curl https://api.daxov.com/v1/calls \
  -H "Authorization: Bearer $ACME_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c7a52-3d1e-4b8a-9f61-2c4d8e7b9a10" \
  -d '{ "character_id": "chr_4fT9kQ2mXw7LbN3pZs8V" }'

The rules

  • 1 to 200 characters, plain ASCII. Surrounding spaces are trimmed. An empty or longer key is 400 invalid_idempotency_key. A value that isn't ASCII is ignored, as if no key were sent.
  • The same key gives back the same call: 201 with the call's status now. For a meeting, the same meeting comes back with 200.
  • Only the character is compared. A different max_seconds or metadata with the same key still gives back the first call.
  • Keys are kept with the call or meeting, per organization and env: a test key and a live key sending the same value each get their own call or meeting, never the other's.

Refusals

StatusCodeWhat it meansWhat to do
409idempotency_in_progressThe first request with this key is still startingTry again in a moment
409idempotency_failedThe first request with this key failedSend a new key
422idempotency_mismatchThis key was used for another characterUse a new key for this character

The tickets in a replay

A repeated call answers with its original ws tickets. A ticket works once, and only for 5 minutes after it was made, so a replay that comes later, or after the browser has connected, gives you the call's id and status but no way in. See The sound socket.

On this page