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.
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-idon 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
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.
- Before you retry with a new key, look up the resource by its
reference-id. For example, list Inquiries filtered byfilter[reference-id]. - If the resource exists, use it instead of creating another one.
- 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:

