Errors and limits

Every failure has the same shape:

{
  "error": {
    "code": "insufficient_credits",
    "message": "This account has no credits left. Upgrade the plan or wait for the next period.",
    "balance": 0
  }
}

code is stable and meant for your code; message is for people. Some errors add fields, such as balance or diagnostics.

Codes

Status	code	When
400	bad_request	The body is not valid JSON, a field is invalid, or both template_id and html were sent.
401	unauthorized	No key, or a key that is wrong or revoked.
402	insufficient_credits	No credits left, and the plan allows no more. balance is included.
403	forbidden	A request from a web page that did not come from the portal, or an expired or altered download link.
404	not_found	The template, image or file does not exist in your account.
409	conflict	A plan limit such as the number of templates or total image size.
413	payload_too_large	The request, a template, the data or an image is over a size limit.
422	invalid_template	The template does not compile or fails while rendering, the HTML is nested too deep, or the document has more pages than your plan allows.
422	strict_mode_rejected	strict was set and the document uses something unsupported. diagnostics lists it.
429	rate_limited	Too many requests. Wait for the Retry-After header.
503	busy	The service is busy. Wait for the Retry-After header and try again.
504	render_timeout	The document took longer than your plan’s time limit.
500	internal_error	Something went wrong on our side. Nothing is charged.

Credits and failures

A credit is taken when a render starts and returned if it fails, for any reason. A 402 means nothing was rendered.

Retrying

429 and 503 are safe to retry after the time in Retry-After. 5xx responses are safe to retry too, because failed renders cost nothing. Do not retry 4xx errors unchanged: they describe the request.

Limits by plan

Your plan sets the request rate per key, the largest input, the most pages per document, the render time limit, how many templates and how much image storage you have, and how long rendered files are kept. See Plans and credits for the numbers.