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:
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.
Choosing a key
Section titled “Choosing a key”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.
Retention
Section titled “Retention”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.
Failed requests and retries
Section titled “Failed requests and retries”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 inRetry-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.