Email OTP API Status Codes: 200, 202, 300, 402, 404 and What to Do
A common mistake with this API is checking the HTTP code. It is always 200. The real result sits in the status field of the JSON body, and it is a string. Once your code reads that field, handling each case is straightforward. Here is the full list.
The statuses
| status | Meaning | What your code should do |
|---|---|---|
| 200 | Success | Use the data in the reply |
| 202 | Still waiting for the email | Wait 30 to 35 seconds and poll again |
| 300 | Order was cancelled | Stop polling. Refund is handled |
| 400 | Bad request, such as a missing domain, an invalid site or an invalid currency | Fix the parameters. Do not retry unchanged |
| 401 | BAD_KEY, the API key is wrong | Check the key and stop |
| 402 | Low balance | Top up, then try again |
| 404 | Not found, such as no stock or a domain not offered for the site | Pick another domain or service |
| 500 | Temporary problem | Wait a little and retry with a limit |
| 503 | The email service is switched off | Stop and check later |
Examples from real replies
{"status":"202","message":"Waiting for code...","messages":[]}
{"status":"200","email_id":"7291834","server":2,"messages":[{"email":"temp.abc123@gmail.com","code":"483920"}]}
{"status":"402","message":"Low balance. Need: 6.5 PKR - Have: 2 PKR"}
{"status":"404","message":"No stock for domain "gmail.com" on site "instagram.com""}A small handler
def handle(res):
s = res.get("status")
if s == "200": return "ok"
if s == "202": return "wait"
if s == "300": return "cancelled"
if s in ("402",): return "topup"
if s in ("404",): return "try_another_domain"
if s in ("500", "503"): return "retry_later"
return "fix_request" # 400, 401 and anything unknownRules that save money
- Never retry a buy call blindly after an error. Check the balance and your order list first.
- Do not loop on 400 or 401. They do not fix themselves.
- On 404 move to the next domain in your fallback list.
- Stop polling on 300.
Refund behaviour
An order that gets no code is cancelled and refunded after 30 minutes. You can cancel earlier with cancelEmail. If the code already arrived, cancel replies that the order was completed and does not refund it.
Logging that helps you later
Log the action, the order id, the status and a short message for every call. When a customer says a code never arrived, you can find the order, see the status history and answer in a minute. Do not log the API key, and do not store full inbox texts longer than you need.
Retry rules in plain words
- Retry a 500 after a short wait, up to a small limit.
- Retry a 202 on the normal poll interval until your deadline.
- Do not retry a 400, a 401 or a 402 until something changes: the request, the key or the balance.
- On a 404 change the domain or the service, then try again.
Questions people ask
Is the status a number?
It is a string, so compare it with quotes in languages that care about types.
What if I get an unknown status?
Treat it as an error, log the whole reply and stop.
Related guides and pages
Create a free OtpGet account and try a temporary email with a small balance.