Errors & retries
Handle invalid input, upload limits, rate limits, and temporary provider failures without losing context.
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 provider failure | 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
As an application-level starting point, cap retries to a small number and increase the delay between attempts. Retry transient failures, not malformed requests. A timed-out request may still have reached the provider, and repeated calls can consume quota. The published API does not document an idempotency-key mechanism.
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.