Docs menu

API referenceErrors and quota

Errors and quota

The stable error codes, what each one means, and how the monthly quota is counted.

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; an image that cannot be read also adds line, its Markdown line, when it is known. 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:

HTTP/1.1 400 · empty_document
{
  "code": "empty_document",
  "error": "The request carried no Markdown to render."
}
HTTP/1.1 413 · payload_too_large
{
  "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": 512,
    "plan": "free"
  }
}
HTTP/1.1 400 · invalid_request
{
  "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.

StatusCodeMeaningWhat to doAlso carriesRetry-After
401unauthorizedThe request carried no API key, or one that is no longer valid.Check the Authorization header and that the key has not been revoked.NoneNo
403account_blockedThe account is blocked and cannot render or download until support lifts it.Contact support; retrying answers the same.NoneNo
403email_unverifiedThe account's email address has not been verified yet.Open the link in the sign-up mail or request a new one, then call again.NoneNo
400invalid_requestA field of the request was missing, of the wrong type or out of range.Fix the field reason names and send the request again.reasonNo
413payload_too_largeThe document, one of its resources or the request as a whole is over a size limit.Send a smaller document, and on preparation_limit make it simpler rather than changing plan.limit, reason, renderer_bound, tableNo
400empty_documentThe request carried no Markdown to render.Send a document with content in it.NoneNo
422too_many_pagesThe rendered document has more pages than were allowed for it: the plan's page limit, or the deployment's ceiling where that is lower.Split the document. limit.plan names the plan whose limit it was, and a plan with a higher one lifts it; limit.plan null means the deployment capped it below the plan, and only the operator can raise that.limitNo
422too_many_resourcesThe document references more resources than one render loads.Reference fewer resources, or split the document into several renders.limitNo
422 / 503resource_fetch_failedA resource the document references could not be loaded.Check that the resource resource_id names is reachable, then retry.reason, resource_idNo
422resource_invalidA resource in the document could not be read, so the document was not rendered.Fix or replace the resource resource_id and line name, or send resources: "lenient" to draw a placeholder.reason, resource_id, lineNo
409idempotency_in_progressA render with the same Idempotency-Key is still running.Wait the Retry-After seconds and retry with the same key.NoneYes
422idempotency_mismatchThe Idempotency-Key was already used for different document or resource content.Use one Idempotency-Key per document; retrying unchanged answers the same.NoneNo
429idempotency_replay_limitThe Idempotency-Key has been replayed as often as the plan allows.Render under a new key, which uses one of the period's documents, or wait for the key to expire.NoneYes
429rate_limitedThe account sent more requests, or asked for more concurrent renders, than its plan allows, or one client address presented more API keys for checking than the service accepts at once.Wait the Retry-After seconds and retry, letting the running renders finish first when limit names concurrency.limitYes
402quota_exhaustedThe account has no documents left for the current period.Check GET /v1/usage, then upgrade the plan or wait for the next period.NoneNo
503quota_unavailableThe account's usage could not be checked, so no render was started.Retry after a short pause; nothing was counted.NoneNo
503queue_fullThe render queue is full; the same request can be sent again shortly.Retry after the Retry-After delay; the document was not counted.NoneYes
422render_timeoutThe render ran past the time allowed for it: the plan's time limit, or the deployment's ceiling where that is lower.Simplify or split the document; retrying unchanged answers the same. limit.plan null means the deployment capped the time below the plan, and only the operator can raise that.limitNo
503render_unavailableNo render capacity was available for this request, or this deployment does not offer what it asked for, such as upload delivery.Retry after a pause, and report it if it persists.NoneNo
422render_failedThe document could not be rendered.Retry once; if it fails again the document is at fault.NoneNo
403plan_requiredThe account's plan does not include what the request asked for.Move to a plan that includes what reason names.reasonNo
400invalid_bundleThe certificate bundle in the request could not be read.Check the bundle's format against what reason says and send it again.reasonNo
400certificate_expiredThe certificate is past its validity period.Seal with a certificate that is still inside its validity period.reasonNo
422signing_failedThe document was rendered but could not be sealed.Retry once, and check the certificate if it fails again.NoneNo
503signing_unavailableSealing is temporarily unavailable.Retry after a pause; reason says what was unavailable.reasonNo
400unknown_signing_identityNo stored certificate of this account matches the one the request named.Name one of the account's stored certificates, or send the bundle in the request.NoneNo
404not_foundThe usage period asked for does not belong to this account, or the path does not exist.Check the path and, on GET /v1/usage, that period is one of this account's periods.NoneNo
405method_not_allowedThe path exists but does not answer this HTTP method; the Allow header lists the ones it does.Use a method the Allow header names.NoneNo
424upload_failedThe storage at upload_url did not accept the PDF or did not answer in time; status is its HTTP status, or null when no answer arrived.Check that the pre-signed URL is still valid and signed for Content-Type: application/pdf, then retry with a fresh one; the document was not counted.statusNo
400template_invalidThe template is not an editor document, or it names a font the editor does not offer.Send a document as GET /v1/templates/{id} returns it, or send markdown or html instead; the error names the fonts.NoneNo
422template_data_invalidThe JSON or CSV data does not fill the template: a field has no value, a value has the wrong format, or a CSV row is malformed.Read issues: each names the data path or CSV line and what is wrong. Nothing was counted.issuesNo
409template_name_takenAnother template of this account already uses that name.Save the template under a name this account is not using.NoneNo
403template_limit_reachedThe account keeps as many templates as its plan allows.Delete a template you no longer use, or upgrade the plan.NoneNo
409template_version_conflictThe template was saved again after the revision this save started from.Read the template again, apply the change to it, and send its revision as base_revision.NoneNo
503templates_unavailableTemplates cannot be stored or read on the server right now.Try again in a few minutes.NoneNo
422language_missingWith standards: "strict", accessible is on, but the PDF has no document language, so it cannot claim PDF/UA-2. Only a converter version that does not detect the language answers this: the current one gives a document without a language the main language of its text, or en. warnings lists every warning of the render; the document was not counted.Send language, or set language in the front matter.warningsNo
422title_missingWith standards: "strict", accessible is on, but the PDF has no title, so it cannot claim PDF/UA-2. Every PDF gets a title from the front matter, the first level-1 heading, the file name or the render time. warnings lists every warning of the render; the document was not counted.Set title in the front matter.warningsNo
422mathml_requiredWith standards: "strict", accessible is on with mathml: false, but PDF/UA-2 needs MathML for the formulas in the document. warnings lists every warning of the render; the document was not counted.Remove mathml: false.warningsNo
422glyph_missingWith standards: "strict", the document has characters that no font can draw: the PDF would show a placeholder in their place. warnings lists every warning of the render, this one with the characters; the document was not counted.Remove these characters or replace them.warningsNo
422unicode_invalidWith standards: "strict", some text maps to U+0000, U+FEFF or U+FFFE, which PDF/A-4 and PDF/UA-2 forbid, so the PDF cannot claim the requested standards. warnings lists every warning of the render; the document was not counted.Remove these characters.warningsNo
422private_use_textWith standards: "strict", accessible is on, but some characters are from the Unicode Private Use Area, which has no standard meaning, so the PDF cannot claim PDF/UA-2. warnings lists every warning of the render; the document was not counted.Replace these characters with standard Unicode characters.warningsNo
422engine_unsupportedWith standards: "strict", a standard was asked for, but this converter version does not write it. warnings lists every warning of the render; the document was not counted.Send standards: "best_effort", or try again after the next release.warningsNo
500internal_errorThe request failed for a reason the service could not classify.Retry after a pause, and report it if it persists.NoneNo

Web app routes#

The codes below come only from the web app's own routes: the editor's download and preview, and the stored certificates on the account page. No /v1 route answers with them, so a client with an API key never meets them. They use the same envelope and are listed here so a code seen in the browser can be looked up.

StatusCodeMeaningWhat to doAlso carriesRetry-After
400identity_limitThe account already stores as many certificates as it is allowed.Delete a stored certificate before adding another.NoneNo
409certificate_name_takenAnother stored certificate of this account already uses that name.Store the certificate under a name this account is not using.NoneNo
403browser_onlyThe endpoint serves the web app and answers no API key.Call the documented /v1 routes with an API key instead.NoneNo
400sign_not_availableThe requested delivery is never sealed, so the seal could not be applied.Ask for the seal on the vector delivery, clearing the state reason names first where there is one.reasonNo
422plan_rasterWith standards: "strict", a standard was asked for on the watermarked delivery, which is a picture of each page and claims no standard. warnings lists every warning of the render; the document was not counted.Ask for the PDF without a watermark.warningsNo

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 is not counted when the render fails, times out, exceeds the page limit, or cannot be dispatched. The refusals that are not counted are listed 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.