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:
{
"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": 512,
"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.
| Status | Code | Meaning | What to do | Also carries | Retry-After |
|---|---|---|---|---|---|
| 401 | unauthorized | The request carried no API key, or one that is no longer valid. | Check the Authorization header and that the key has not been revoked. | None | No |
| 403 | account_blocked | The account is blocked and cannot render or download until support lifts it. | Contact support; retrying answers the same. | None | No |
| 403 | email_unverified | The 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. | None | No |
| 400 | invalid_request | A field of the request was missing, of the wrong type or out of range. | Fix the field reason names and send the request again. | reason | No |
| 413 | payload_too_large | The 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, table | No |
| 400 | empty_document | The request carried no Markdown to render. | Send a document with content in it. | None | No |
| 422 | too_many_pages | The 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. | limit | No |
| 422 | too_many_resources | The document references more resources than one render loads. | Reference fewer resources, or split the document into several renders. | limit | No |
| 422 / 503 | resource_fetch_failed | A resource the document references could not be loaded. | Check that the resource resource_id names is reachable, then retry. | reason, resource_id | No |
| 422 | resource_invalid | A 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, line | No |
| 409 | idempotency_in_progress | A render with the same Idempotency-Key is still running. | Wait the Retry-After seconds and retry with the same key. | None | Yes |
| 422 | idempotency_mismatch | The Idempotency-Key was already used for different document or resource content. | Use one Idempotency-Key per document; retrying unchanged answers the same. | None | No |
| 429 | idempotency_replay_limit | The 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. | None | Yes |
| 429 | rate_limited | The 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. | limit | Yes |
| 402 | quota_exhausted | The account has no documents left for the current period. | Check GET /v1/usage, then upgrade the plan or wait for the next period. | None | No |
| 503 | quota_unavailable | The account's usage could not be checked, so no render was started. | Retry after a short pause; nothing was counted. | None | No |
| 503 | queue_full | The render queue is full; the same request can be sent again shortly. | Retry after the Retry-After delay; the document was not counted. | None | Yes |
| 422 | render_timeout | The 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. | limit | No |
| 503 | render_unavailable | No 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. | None | No |
| 422 | render_failed | The document could not be rendered. | Retry once; if it fails again the document is at fault. | None | No |
| 403 | plan_required | The account's plan does not include what the request asked for. | Move to a plan that includes what reason names. | reason | No |
| 400 | invalid_bundle | The certificate bundle in the request could not be read. | Check the bundle's format against what reason says and send it again. | reason | No |
| 400 | certificate_expired | The certificate is past its validity period. | Seal with a certificate that is still inside its validity period. | reason | No |
| 422 | signing_failed | The document was rendered but could not be sealed. | Retry once, and check the certificate if it fails again. | None | No |
| 503 | signing_unavailable | Sealing is temporarily unavailable. | Retry after a pause; reason says what was unavailable. | reason | No |
| 400 | unknown_signing_identity | No 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. | None | No |
| 404 | not_found | The 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. | None | No |
| 405 | method_not_allowed | The path exists but does not answer this HTTP method; the Allow header lists the ones it does. | Use a method the Allow header names. | None | No |
| 424 | upload_failed | The 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. | status | No |
| 400 | template_invalid | The 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. | None | No |
| 422 | template_data_invalid | The 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. | issues | No |
| 409 | template_name_taken | Another template of this account already uses that name. | Save the template under a name this account is not using. | None | No |
| 403 | template_limit_reached | The account keeps as many templates as its plan allows. | Delete a template you no longer use, or upgrade the plan. | None | No |
| 409 | template_version_conflict | The 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. | None | No |
| 503 | templates_unavailable | Templates cannot be stored or read on the server right now. | Try again in a few minutes. | None | No |
| 422 | language_missing | With 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. | warnings | No |
| 422 | title_missing | With 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. | warnings | No |
| 422 | mathml_required | With 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. | warnings | No |
| 422 | glyph_missing | With 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. | warnings | No |
| 422 | unicode_invalid | With 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. | warnings | No |
| 422 | private_use_text | With 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. | warnings | No |
| 422 | engine_unsupported | With 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. | warnings | No |
| 500 | internal_error | The request failed for a reason the service could not classify. | Retry after a pause, and report it if it persists. | None | No |
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.
| Status | Code | Meaning | What to do | Also carries | Retry-After |
|---|---|---|---|---|---|
| 400 | identity_limit | The account already stores as many certificates as it is allowed. | Delete a stored certificate before adding another. | None | No |
| 409 | certificate_name_taken | Another stored certificate of this account already uses that name. | Store the certificate under a name this account is not using. | None | No |
| 403 | browser_only | The endpoint serves the web app and answers no API key. | Call the documented /v1 routes with an API key instead. | None | No |
| 400 | sign_not_available | The 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. | reason | No |
| 422 | plan_raster | With 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. | warnings | No |
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.