Idempotency

Send an Idempotency-Key header with requests that create or start something (POST /videos, POST /videos/{id}/complete, POST /videos/{id}/reprocess). If the same key arrives again (after a timeout or dropped connection), you get the first result back with a replay header, instead of creating it twice. Like Stripe's idempotency keys.

How it works

• Format: 1–255 printable ASCII characters (no spaces). Choose any unique value per request.
• Replay: same key, same request = the first response, with header Idempotent-Replayed: true. Store the videoId immediately on the first request (don't wait to see if it's a replay).
• Reuse error: same key, different request (body, path or method) = 409 IDEMPOTENCY_KEY_REUSED. Use a new key.
• In-progress error: same key while the first request is still processing = 409 IDEMPOTENCY_IN_PROGRESS. Retry in a moment.
• Only 2xx stored: after an error the key is free, so a corrected retry works.
• Expires: stored for 24 hours.
• Dry runs skip keys: ?dryRun=true doesn't use or check the key.

Example

First request
POST /videos HTTP/1.1
Idempotency-Key: my-lesson-upload-20250101-abc123
Content-Type: application/json

{ "fileName": "lesson.mp4", "sizeBytes": 1048576 }

200 OK
{ "videoId": "3f1c0a9e5b7d4c2a8e6f1b0d9c7a5e3f", "partSize": 67108864, … }

Retry with same key (e.g., connection dropped)
POST /videos HTTP/1.1
Idempotency-Key: my-lesson-upload-20250101-abc123

200 OK (same response as first time)
Idempotent-Replayed: true
{ "videoId": "3f1c0a9e5b7d4c2a8e6f1b0d9c7a5e3f", "partSize": 67108864, … }