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/callsPOST
/v1/meetingsHow 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_secondsormetadatawith 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
| Status | Code | What it means | What to do |
|---|---|---|---|
| 409 | idempotency_in_progress | The first request with this key is still starting | Try again in a moment |
| 409 | idempotency_failed | The first request with this key failed | Send a new key |
| 422 | idempotency_mismatch | This key was used for another character | Use 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.