PlatformErrors
Errors
Errors use the same envelope as success: success: false plus an error object with a stable machine code, a human message, optional details, and a request_id. Build retry logic against code, not the message text.
Error shape
error
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit of 200/min exceeded",
"details": { "retry_after_ms": 41000 },
"request_id": "req_7c0f1a2b"
}
}Error codes
| HTTP | Code | Meaning | Retry? |
|---|---|---|---|
| 400 | INVALID_PARAMS | Invalid body — failed schema validation, or neither/both of url/html. | No |
| 401 | INVALID_API_KEY | A supplied x-api-key is malformed, expired, or revoked. | No |
| 401 | INVALID_TOKEN | No credentials at all (missing x-api-key) or an expired dashboard JWT. | No |
| 403 | FEATURE_NOT_AVAILABLE | A parameter requires a higher plan. | No |
| 403 | ACCOUNT_SUSPENDED | The account is suspended. | No |
| 404 | NOT_FOUND | Unknown job id or route. | No |
| 429 | QUOTA_EXCEEDED | Out of credits for the period. | After top-up |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests/min or too many concurrent renders. | After Retry-After |
| 500 | INTERNAL_ERROR | Unexpected server error. | Yes, with backoff |
| 502 | ENGINE_UNAVAILABLE | The render engine is unreachable. | Yes, with backoff |
| 502 | RENDER_FAILED | The page failed to render (navigation/capture error). | Sometimes |
| 503 | SERVICE_UNAVAILABLE | A dependency is temporarily down. | Yes, with backoff |
| 504 | TIMEOUT | The render exceeded its timeout. | Yes — raise timeout or simplify |
Failed renders are free
Any non-cache failure refunds the reserved credits automatically — RENDER_FAILED, TIMEOUT, and ENGINE_UNAVAILABLE never cost you. Only successful, non-cached renders are billed.