Skip to navigation

Idempotence

The Persona API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create an Inquiry does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one Inquiry is created.

To perform an idempotent request, provide an additional Idempotency-Key header to the request.

Idempotency-Key: <key>

Persona’s idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors.

Keys are eligible and automatically pruned from the system after they’re at least 24 hours old. If a key is reused after pruning, a new request is generated. The idempotency layer compares incoming parameters to those of the original request and errors unless they’re the same to prevent accidental misuse.

Where are my API logs?

When you retry an API call with an idempotency key and Persona returns a saved response, we do not create a new API log. This helps to prevent clutter and, in the case of errors, makes it easier to diagnose the initial issue.

All POST and PATCH requests accept idempotency keys. Sending idempotency keys in GET, PUT, and DELETE requests has no effect and should be avoided, as these requests are idempotent by definition.

Recommendations for choosing Idempotency Key values

The idempotency key should generally be unique per endpoint and operation. For example, an idempotency key for creating a resource should not conflict with one for updating a resource. It’s best practice, to use UUIDs or other cryptographically random strings to ensure uniqueness. Avoid using reference IDs as idempotency keys.

Retrying requests safely

Idempotency keys only protect you if your retry logic reuses them correctly. This section describes how to manage keys and how to respond to each kind of result. For more on handling specific errors, see Network errors and Server errors.

Key lifecycle

  • Generate one key per logical operation. Create a random UUID before the first attempt, and persist it with the job or record that triggers the request. Every retry of that operation reuses the same key with the same path and the same request body.
  • Don’t share a key between different operations. For example, creating an Inquiry and later updating it are two operations and need two keys.
  • Always set a reference-id on objects you create. If a result is ever uncertain, you can use the reference ID to find the object later.

Keys apply to POST and PATCH requests. GET, PUT, and DELETE requests ignore the Idempotency-Key header.

What to do with each response

ResponseWhat to doIdempotency key
No response (timeout, connection reset)Retry with backoff.Same key
429 Too Many RequestsBack off and retry. 429 responses are never saved under the key.Same key
400 with title Idempotency errorThe key is either still in use by an in-progress request, or was reused for a different request. If your client only reuses a key to retry the identical request, wait and retry with the same key. Otherwise, fix your key handling.Same key if retrying the identical request; otherwise new key
Other 4xxFix the request. Don’t retry it unchanged.New key
5xxThe response is saved under the key for up to 24 hours, so a retry with the same key returns the same error. Follow recovering from a 5xx below.New key
2xxDone.—

All responses to POST and PATCH requests other than 429 are saved under the key for 24 hours, including 2xx, 4xx, and 5xx responses. A retry with the same key returns the saved response.

Recovering from a 5xx

Treat the result of a 5xx as indeterminate: a server error can occur after records were already created.

  1. Before you retry with a new key, look up the resource by its reference-id. For example, list Inquiries filtered by filter[reference-id].
  2. If the resource exists, use it instead of creating another one.
  3. If it doesn’t exist, retry with a new idempotency key.

If 5xx errors persist across new keys, check the status page and contact support with the request details and the idempotency key.

Backoff

Use exponential backoff with jitter, and cap the number of attempts. A backoff interval of 5, 10, 20, 40 seconds, and so forth is commonly used. Add a random amount of jitter to each delay so that many clients don’t retry at the same moment. When you reach the attempt cap, queue the job for later or alert someone instead of retrying indefinitely.

Example

The following pseudocode shows these rules together:

key = new_uuid() # generated once, stored with the job
attempt = 0
loop:
attempt = attempt + 1
if attempt > MAX_ATTEMPTS:
queue_job_or_alert()
stop
response = send(request, idempotency_key = key)
if response is a network error or timeout:
wait(backoff_with_jitter(attempt)); continue # same key
if response.status == 429:
wait(backoff_with_jitter(attempt)); continue # same key
if response.status == 400 and response.title == "Idempotency error":
wait(backoff_with_jitter(attempt)); continue # same key (identical request only)
if response.status is 5xx:
existing = find_by_reference_id(request.reference_id)
if existing: use(existing); stop
key = new_uuid() # new key
wait(backoff_with_jitter(attempt)); continue
if response.status is 2xx:
use(response); stop
# any other 4xx: not retryable unchanged
fix_request_or_report(response); stop