Errors and quota

This page is the code reference: what each refusal means and what to do about it. The numbers behind the refusals are on Limits: what each plan allows, how a document is measured and what a refusal costs.

Error format#

Every error is a JSON body with at least two fields. code is the stable contract: it never changes meaning, so script against it. error is a sentence for people and may be reworded at any time. A refusal against a limit (413 payload_too_large, 422 too_many_resources, 422 too_many_pages, 429 rate_limited and 422 render_timeout) adds limit: the limit's name, the value that was exceeded and the plan it came from, so a client reads the number without parsing the sentence. The names are the plan columns Limits lists. One refusal in that set carries no limit: a 413 with reason preparation_limit, where the renderer, not the plan, set the bound. Treat limit as optional and read reason when it is missing. A failed remote resource adds reason and resource_id. When the server knows how long to wait, a Retry-After header gives the number of seconds. Only the codes the table marks send it.

The three shapes, as the document publishes them:

{
  "code": "empty_document",
  "error": "The request carried no Markdown to render."
}

{
  "code": "payload_too_large",
  "error": "The document, one of its resources or the request as a whole is over a size limit.",
  "reason": "markdown_limit",
  "limit": {
    "name": "markdown_kb",
    "value": 256,
    "plan": "free"
  }
}

{
  "code": "invalid_request",
  "error": "A field of the request was missing, of the wrong type or out of range.",
  "reason": "render_options"
}

401 responses also carry WWW-Authenticate: Bearer. All API responses, errors included, are sent with Cache-Control: no-store.

Error codes#

The codes below are every value the documented routes can produce, with the fields the envelope carries beside code and error. The sentences are the current wording and may change.

Monthly quota#

Each plan includes a number of documents per period; the counts are on Limits. Periods start each month at 00:00 UTC on the day the account signed up or, after a purchase, on the day of the purchase. A monthly upgrade starts a new period on its day. The counter is transactional in the database, so it is exact under concurrency. It counts only PDFs that were actually served: a document is reserved before the render starts and returned to your period when the render fails, times out, exceeds the page limit, or cannot be dispatched. Which refusals return the document to your period is on Limits.

When the period's documents are used up, /v1/render answers 402 quota_exhausted; the message says the period's documents are used up and links to pricing. Grants add documents to the period. Check credits_used, credits_included, credits_granted and the period boundaries with GET /v1/usage.