Retries and idempotency

Sometimes a request fails, or you never get its response: a timeout on your side, a dropped connection, or a 502, 503 or 504 from the network. This page says when you can simply send the request again.

The API has no idempotency key header. Each endpoint’s page has a “Retry safety” section that says whether that endpoint is safe to send again after a lost response, and how.

When to retry

Response	Retry?
400, 401, 403, 404	No. The same request gets the same answer. Fix the cause first; see Errors.
409 business_exists	No. On a retried create it means the first request succeeded; see Create a business.
409 business_not_ready	Yes, after you repeat Create a business with the same external_id.
409 billing_not_ready	No. Contact Lazy.
429 rate_limited	Yes, after the wait that Rate limits describes.
500 internal_error	Yes, following the endpoint’s “Retry safety” section. For a purchase, a 500 means nothing was bought.
502, 503, 504, or no response	Yes, following the endpoint’s “Retry safety” section. The request may or may not have taken effect.

Wait before each retry, and wait longer each time: for example 1, 2, 4 and 8 seconds, then give up and alert. Add a random delay of up to a second so many failed requests do not retry at the same moment.

Purchases: top-ups and scan-period extensions

Top up documents and Extend the scan period are not safe to retry after a lost response: a purchase that succeeded and is sent again is bought, and billed, twice. A 500 internal_error means nothing was bought, so retry it freely. When you lost the response instead, check whether the purchase happened before you retry:

1. Before the purchase, read the business’s usage with Get usage. Keep its reset_at and the limit you are raising: max_docs for a top-up, max_email_scan_days for a scan-period extension.
2. Send the purchase.
3. If you lose the response, read the usage again.
4. If the limit rose, the purchase happened. Do not retry.
5. If the limit did not rise and reset_at is unchanged, the purchase did not happen. Send it again.
6. For a top-up only: if reset_at changed, a new monthly period started and set max_docs back to the business’s monthly allowance, so the two readings cannot be compared. Decide from the new usage whether the business still needs a top-up.

Do not send two purchases for the same business at the same time. The recipe cannot tell them apart.