Read status and response together
Check the HTTP status before using data, and check the JSON success field before treating a request as complete. A proxy can return HTML instead of JSON during an outage. Treat an unexpected body as a failed request; never interpret a parsing error as an empty inbox.
Send credentials only in X-API-Key to https://cleantempmail.com. Do not rely on a Referer or Origin header to authenticate an automation client. Turnstile browser verification and API key authentication are separate paths.
Decide whether retrying can help
| Response | What to check | Next action |
|---|---|---|
| 200 with an empty inbox | The test's address, sender logs and elapsed time. | Continue bounded polling; this is not an API error. |
| 400 | Required fields, JSON shape and address syntax. | Correct the request before retrying. |
| 401 | Missing, invalid or inactive key; accidental URL credentials. | Stop. Check the key privately and use the header. |
| 403 | Access policy or an edge security response, including whether the body is HTML. | Investigate the policy; repeating the same request does not fix authorization. |
| 404 on message detail | A stale, expired, deleted or incorrect message ID. | Check current inbox summaries. Do not retry a stale ID indefinitely. |
| 409 during address generation | An explicitly selected domain is unavailable. | Refresh the public domain list and intentionally choose another domain, or generate without a fixed domain. |
| 429 | Rate limiting versus daily or total quota exhaustion. | For rate limits, honor Retry-After. For exhausted quota, stop and check usage. |
| 500, 502, 503, 504 or transport timeout | A temporary service, proxy or network failure. | Retry reads with delay and a strict attempt/deadline budget. |
Not every 429 means “wait one second”
A quota rejection can include usage.daily_limit, usage.remaining_today, usage.total_limit and usage.remaining_total. A positive limit with zero remaining allowance means that budget is exhausted. An unlimited allowance can use -1 as its remaining value; do not mistake it for exhausted quota.
Use the quota checker to resolve uncertainty. A depleted total allowance will not recover through rapid retries, and a daily limit needs the applicable reset rather than another tight loop. If the response instead reports rate limiting, spread work across time and follow Retry-After, which may be seconds or an HTTP date. Do not rotate keys to evade protection.
A bounded retry policy
For inbox reads, start with a five-second interval, a 90-second overall waiting budget and at most 18 attempts. The example helpers implement those defaults and impose a per-request timeout. Increase a server-requested delay when necessary; if it would run past the deadline, stop. A request that fails at the network layer still counts as an attempt.
Production test suites can add exponential backoff and jitter for repeated transient failures. Keep the delay under an overall deadline, never retry earlier than the server requests, and include outer CI reruns in your request budget. Recovery is not guaranteed merely because an error is retryable.
Take care with actions that change state
A timeout after generating an address does not tell you whether the server already handled the request. Repeating it can generate a second address. Keep the returned address when you receive one; if a generation response is lost, treat the replacement as a new test run. Do not assume an idempotency header is supported where the reference does not document it.
Before clearing an inbox, confirm it belongs to this test run. Do not perform destructive cleanup on a shared address just to make a retry pass. Read-only polling and destructive actions should not share an indiscriminate retry wrapper.
Collect a useful support report
Keep the UTC failure time, endpoint path without private query values, HTTP status, attempt count and duration. Include an edge request identifier if one is present. Never attach the API key, OTP, magic link, complete message content or raw authorization headers. These measurements help distinguish a repeatable invalid request from a temporary transport failure.
See the API reference for current request fields and the budget guide for the effect of repeated polling.