Alfa

Idempotency

A request can succeed on the server while its response is lost on the way back. Retrying it must not publish a job twice, spend credits twice or email a candidate twice. Operations that create, spend or send accept an Idempotency-Key header for this.

  • Make up a unique key for each request, such as a UUID, and send the same key on every retry of that request.
  • A retry after the request succeeded returns the first response, marked Idempotent-Replayed: true, without doing the work again.
  • A retry while the first attempt is still running is 409 idempotency_in_progress. Wait a moment and retry.
  • Reusing a key for a different request is 422 idempotency_key_reused.
  • Only successes are kept, for 24 hours. After an error, a retry with the same key runs again.
POST /v1/jobs/8724/publish
Idempotency-Key: 3f0c1d8e-6b6a-4f7e-9a51-0d2c5e7b9f10

The reference lists the header on each operation that accepts it.