Documentation
Errors
Every error code, its HTTP status, and the correct handling.
Errors always use the same envelope:
error envelope
{
"error": {
"code": "insufficient_credits",
"message": "Your page balance is exhausted.",
"requestId": "req_9f2c4a7b1d",
"details": [{ "path": "html", "message": "Required" }]
}
}| HTTP | Code | What to do |
|---|---|---|
| 400 | invalid_request | Read details[] and fix the body. |
| 401 | invalid_api_key | Check the header, or rotate the key. |
| 402 | insufficient_credits | Upgrade or top up. Nothing was rendered. |
| 403 | forbidden_url | The URL is private or unsupported. Fetch the content yourself and send HTML. |
| 404 | not_found | Unknown endpoint. |
| 413 | payload_too_large | JSON ≤ 6 MB, Office/PDF uploads ≤ 10 MB. |
| 422 | render_failed | Engine could not render. Check HTML validity; retry once with backoff. |
| 429 | rate_limited | Honour Retry-After, then retry with jitter. |
| 500 | internal_error | Retry with backoff. Not charged. |
Retry policy
Retry 429, 500, 503 and network errors with exponential backoff and jitter. Do not retry 400, 401, 402, 403 or 413 — the request will never succeed unchanged.
Need something not covered? Contact support.