OTP API Reliability: Retries, Timeouts and Idempotency
An idempotency key lets an API client retry a request without the work happening twice. For an OTP API that means one new Idempotency-Key per order, reused only when resending that same request after a timeout; 15 seconds allowed for the call; Retry-After honoured on HTTP 429; and out-of-stock treated as "nothing charged, try later".
Aimed at integrators taking an Почта script from a demo to production. Every behaviour below comes from the public API reference (revision of 10 October 2026); the API docs page shows the limits that apply to your account.
What an idempotency key does in a REST API
A POST creates something. If the response is lost on the way back, the client cannot tell whether the order exists. With an idempotency key, the client sends a unique value with the request; the server stores the first successful response under that value and replays it when the same request arrives again. On Почта:
- Generate a new UUID for every new order, and reuse it only to resend that same request.
- Keys belong to your account and are kept for 24 hours.
- The same key with a different body or endpoint returns 409
DUPLICATE_REQUEST. - The same key while the first request is still running also returns 409
DUPLICATE_REQUEST; retry a second later. - Error responses are not stored, so a retry after a 4xx or 5xx really runs again, and can succeed.
- The same header protects
POST /v1/orders/{id}/rerentand paidnext-codecalls.
The classic bug is a retry with a fresh UUID after a timeout: two inboxes, two charges. The Gmail OTP API overview shows where the header sits in the basic flow.
How to handle an API timeout
- Creating an order.
POST /v1/orderswaits for an inbox to be allocated: usually about 0.3 seconds, up to about 10 seconds at rare peaks. Set a client timeout of at least 15 seconds, or 60 seconds withquantityabove 1, and never retry early with a new key. - Reading an order.
GET /v1/orders/{id}only reads, so it is safe to repeat at any time; a failed poll simply waits for the next tick. - Cancelling.
POST /v1/orders/{id}/cancelis safe to repeat: once an order has leftwaiting_code, the call answersORDER_NOT_CANCELLABLE, so nothing is refunded twice. - Unknown or known outcome. A timeout or dropped connection means you do not know what happened: resend with the same key. An HTTP response with an error body means you do: act on
error.code, which is stable, rather than on the HTTP status, which several codes share.
What to do with each error code
error.code |
HTTP | Retry? | Action |
|---|---|---|---|
| none (timeout) | – | Yes, same key | Resend after a short pause |
RATE_LIMITED |
429 | After Retry-After |
Slow down (next section) |
WAITING_LIMIT_REACHED |
429 | Later | Too many orders waiting for a first code; let some finish or cancel them |
NO_MAILS_AVAILABLE |
503 | Later, with backoff | Temporarily out for that service; nothing charged; try the other domain |
OUT_OF_STOCK |
409 | Later | No inbox of that type right now; nothing charged |
DOMAIN_UNAVAILABLE |
409 | Not with that domain |
Send gmail.com, or omit domain |
PROVIDER_ERROR |
502 | After a few seconds | A temporary error |
MAINTENANCE |
503 | Later | Creating and cancelling orders are paused |
INSUFFICIENT_BALANCE |
402 | No | Stop and alert; top up |
VALIDATION_ERROR, SERVICE_DISABLED |
400, 409 | No | Fix the body; take codes from GET /v1/services |
QUANTITY_EXCEEDED |
400 | Split the request | Over the per-call maximum |
UNAUTHORIZED |
401 | No | Key missing, wrong, or replaced with Generate new key |
You are charged only when an inbox is issued, so none of these errors costs money.
Rate limits: honour Retry-After and budget your polling
Limits apply per API key: by default 20 requests per second and 900 per minute. Your account may have its own values, and the current ones are on the docs page.
- Going over returns HTTP 429,
RATE_LIMITED, withRetry-After: <seconds>. Sleep at least that long, and add a little random jitter when many workers retry together. POST /v1/ordersalso answersRATE_LIMITEDwhile the account has cancelled too many orders without a code in the last 60 minutes; renting pauses until that rate drops. A loop that rents, gives up after 20 seconds and rents again will hit it, so wait longer per order instead.- Budget: polling every 4 seconds costs 15 requests a minute per open order, so 900 a minute covers about 60 orders waiting at once, minus creation and cancel calls. Workers that share a key should share one rate limiter.
- One call can rent several inboxes with
quantity, up to the per-request maximum shown on the docs page; above it you getQUANTITY_EXCEEDED. A successful response can hold fewer orders than you asked for, so countdata[].
Polling and deadlines
- Poll every 3–5 seconds while the status is
waiting_code; faster polling returns the same stored data and eats your limit. - Read
codeDeadlineAtfrom each order instead of hard-coding a wait. It is 25 minutes at most and can be shorter (the rent page shows the waiting time before you confirm); at that moment the order cancels itself with a 100% refund, as the rental refund rules state. - After
completed, poll every 5–10 seconds only while you still need codes, and stop whennextCodeBlockedis true. otp[]is ordered oldest first. A value longer than 80 characters, with a line break or HTML, is the whole email rather than a code.- There are no webhooks: polling is the only way to receive codes, so build one polling loop with a shared limiter rather than a thread per order.
A retry wrapper in Python
import random, time, uuid, requests
HOST = "onemail.wtf"
H = {"Authorization": "Bearer YOUR_API_KEY"}
LATER = {"NO_MAILS_AVAILABLE", "OUT_OF_STOCK", "PROVIDER_ERROR", "MAINTENANCE", "WAITING_LIMIT_REACHED"}
class ApiError(Exception):
pass
def create_order(service, domain="gmail.com", attempts=5):
key = str(uuid.uuid4()) # one key for this order, reused on every retry below
for attempt in range(attempts):
try:
r = requests.post(f"https://{HOST}/v1/orders", json={"service": service, "domain": domain},
headers={**H, "Idempotency-Key": key}, timeout=15)
except (requests.Timeout, requests.ConnectionError):
time.sleep(2 ** attempt) # outcome unknown: the same key prevents a duplicate
continue
body = r.json()
if body["success"]:
return body["data"] # a list of orders
code = body["error"]["code"]
if code == "RATE_LIMITED":
time.sleep(int(r.headers.get("Retry-After", "5")) + random.random())
elif code == "DUPLICATE_REQUEST":
time.sleep(1) # the first request with this key is still running
elif code in LATER:
time.sleep(min(60, 5 * 2 ** attempt))
else:
raise ApiError(code) # INSUFFICIENT_BALANCE, VALIDATION_ERROR, DOMAIN_UNAVAILABLE...
raise ApiError("GAVE_UP")
Catch DOMAIN_UNAVAILABLE one level up and call again with gmail.com. The polling side follows the same idea; the Python example has a complete loop, and the testing guide adds a fallback from iCloud to Gmail.
What to log for each order
- Your own request ID and the
Idempotency-Keyit used. orderId,service,domain,emailand the price, written as soon as the order exists.- Each status change with a timestamp, plus
codeDeadlineAtand thereceivedAtof each code. - For failures:
error.code, the HTTP status,Retry-Afterand how long the call took.
Never log the API key. Codes are short-lived, but keep them out of shared logs anyway. Once a week, compare your log with an Export Excel from the History page, so a missed refund or a duplicate stands out.
Frequently asked questions
Is there a webhook instead of polling?
No. Codes are read by polling GET /v1/orders/{id} every 3–5 seconds. The system checks for new mail every few seconds on its own, so calling more often does not speed delivery.
Why do I get RATE_LIMITED below 20 requests per second?
Either the per-minute limit, by default 900 requests across every worker using the key, or the pause on renting after too many cancellations without a code in the last hour. The response looks the same, so check both.
What happens to an order if my server crashes mid-poll?
Nothing: the order keeps running. Store orderId right after creation and resume polling on restart. An order that got no code before its deadline has already been refunded.
Can two of my servers share one API key?
Yes, but the limits apply per key, so give them one shared limiter. Idempotency keys belong to the account, and random UUIDs from different servers will not collide.
