# 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:

```sh
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

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

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

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`](/docs/api-reference/response-headers/). 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](/docs/api-reference/errors/) for status codes and handling guidance.
