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 Почта:

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

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.

Polling and deadlines

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

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.

Related guides

Get your verification code now

Sign up free. You are only charged when an inbox is issued. No code within 25 minutes — 100% refunded automatically.

Can't find the service you need? Use Add service on the rental page and we will add it if our infrastructure supports it.

Need a Gmail account you can sign in to, not just a code? See buy short-lived Gmail accounts · Refund and warranty