Skip to main content
The Bota API accepts an optional Idempotency-Key header on authenticated POST, PUT, and PATCH requests. The current compatibility mechanism can reduce duplicate side effects, but it is not an exactly-once guarantee.
Do not use the header as your only recovery mechanism. Persist the operation’s key and any returned resource ID, and reconcile current resource state after a timeout, connection loss, or other ambiguous response.

​
Current Behavior

For the generic middleware, a key is scoped to the authenticated project, HTTP method, and request path:
  1. The first request creates a key record and continues processing.
  2. If response persistence finishes successfully, a later matching request can receive the captured JSON status and body.
  3. A concurrent replay, or a replay whose response was not persisted, returns 409 with error code idempotency_conflict.
  4. Reusing the key on a different method or path also returns idempotency_conflict.
Request bodies are not compared. Reusing a key with a different body on the same method and path can therefore replay the earlier response. Never reuse a key for a different payload or logical operation. Response capture is asynchronous. A response can reach the client before its replay record is saved, and persistence failures do not fail the original request. JSON error responses, including a 5xx response, can also be captured and replayed.

​
Header Requirements

The database key can remain reserved after the 24-hour lookup window if cleanup has not removed it. Treat keys as permanently single-use; do not assume they become reusable after 24 hours.

​
Example

Generate the key before the first request and store it with your own operation record:
If the response is lost:
  1. Reconcile the operation through current API state or an identifier you persist locally.
  2. If reconciliation does not establish an outcome, retry the exact same method, path, and body with the same key.
  3. Treat 409 idempotency_conflict as an ambiguous result requiring reconciliation; do not switch to a new key automatically.
  4. Treat a replayed 5xx as an error result, not proof that no side effect occurred.
409

​
Endpoint-Specific Contracts

Some endpoints implement their own durable identity or retry contract. Those endpoint-specific rules take precedence over this generic header behavior. For example, Encrypted Upload v2 recovery deliberately bypasses generic response caching so that each retry rechecks current authorization and binding state.

​
Integration Rules

  • Generate keys client-side before sending the first request.
  • Store the key and the exact request parameters together.
  • Use a different key for every distinct logical operation.
  • Serialize retries for one key; do not send concurrent attempts.
  • Persist returned resource IDs and poll current state after ambiguous results.
  • Do not assume the header makes upload completion, job creation, or other multi-step workflows exactly once.