Guide
Idempotency
Retry write requests safely with X-Idempotency-Key.
Networks fail. To make retries safe, every write request (POST, PUT, PATCH, DELETE) must carry an
idempotency key:
X-Idempotency-Key: create-job-REQ-1042
A write without the header is rejected with 400 VALIDATION_ERROR. The token endpoints are the exception.
How keys behave
Keys are scoped to your partner account and the tenant in X-Tenant-ID, and are kept for 24 hours.
| You send | Result |
|---|---|
| A new key | The request runs normally. |
| The same key and the same body again | The original status and response body are returned; nothing runs twice. |
| The same key with a different body | 409 IDEMPOTENCY_CONFLICT |
| The same key while the first request is still running | 409 IDEMPOTENCY_CONFLICT with retryable: true — wait and retry. |
Only responses below 500 are stored. If the original request failed with a server error, retrying with the
same key runs it again.
Choosing keys
- Use one key per logical operation, and reuse it for every retry of that operation.
- Derive it from your own data where you can, e.g.
create-job-<external_job_id>ordecision-<candidate_id>-<your event id>. A random UUID stored with the pending operation also works. - Don't reuse a key for a different operation.
If the idempotency store is briefly unavailable the API returns 503 SERVICE_UNAVAILABLE; retry with the same
key after a short backoff.