Skip to content

Idempotent requests

Use an idempotency key to retry a write after a timeout or connection failure without creating duplicate users, conversations, or messages. Generate a key for each new operation, then reuse that key and the same request body for retries.

Every POST and PATCH endpoint requires the Idempotency-Key header:

Terminal window
curl https://optlo.com/api/v1/users \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3eaac46a-0e3f-46b5-93d4-2975162c8f42" \
--data '{"email":"sam@example.com","name":"Sam Rivera"}'

If you do not receive a response, send the request again with the same key. A retained successful operation returns its original response, even if the resource has since changed. Retries still require valid credentials, permissions, and any applicable workspace or resource checks.

Use a randomly generated value such as a UUID. Keys must contain 1–128 visible ASCII characters, with no spaces. A missing or invalid key returns 400 invalid_request.

Keys are scoped to the workspace, API key, operation, and resource path. Retry with the same API key and path; switching API keys, including after rotation, starts a separate operation.

Reusing a retained key with different validated input returns 409 conflict. Keep the original request body for retries. Use a new key when you intend to perform a new operation.

GET and DELETE endpoints do not use idempotency keys.

Retry protection lasts for 24 hours. After the retained record expires, reusing the same key can perform the operation again. Retry uncertain results within this window; afterwards, check the resource’s state before starting another write.

Error responses are not stored as the final result. A retry with the same key can succeed after a temporary failure. Previously completed work is reused, and retained retries consume no additional write allowance.

  • After a timeout, connection failure, or transient 500, retry the same request with backoff.
  • For 429, wait for the delay in Retry-After. A write-allowance rejection does not consume capacity, so the same key can succeed once capacity frees up.
  • A failure after a write has been admitted can still count toward the write allowance. Retrying with the retained key does not consume it again.
  • Resolve validation, permission, and conflict errors before retrying. If you change the intended input, generate a new key.

See error responses for status codes and handling guidance.