Errors & retries
Handle invalid input, upload limits, rate limits, and temporary service interruptions in your integration.
Application error format
API errors use the following documented envelope. RapidAPI gateway errors may use a different body, so check the HTTP status before assuming a JSON shape.
{
"error": "...",
"message": "...",
"timestamp": "...",
"path": "..."
}Handle each failure appropriately
| Status | Meaning | What to do |
|---|---|---|
400 | Bad or missing input | Check field names, image readability, and the request body. Fix the input before retrying. |
413 | Upload exceeds 20 MB | Reduce file size locally before resubmitting. |
429 | Rate limit exceeded | Respect Retry-After if present. Reduce concurrency and check your plan. |
502 | Temporary service interruption | Use bounded retries with exponential backoff and jitter. |
Authentication failures
For a gateway authentication or authorization error, verify your RapidAPI key, selected host, and active subscription. Do not repeatedly retry a request with invalid credentials.
Retry deliberately
Limit retries and increase the delay between attempts. Retry transient failures after checking the status; correct malformed requests first. A timed-out request may still have been processed, so account for possible duplicate calls and quota usage. Check the API reference before relying on idempotency behavior.
Log enough to investigate
Record the endpoint, HTTP status, and a redacted diagnostic message. Avoid logging API keys, uploaded images, extracted document fields, or full face-analysis responses.