Errors
Every refusal is JSON with the same two keys, plus whatever a program has to act on.
The shape of a refusal#
Every refusal is JSON with the same two keys, plus whatever a
program has to act on. Branch on the extra fields, never on
detail — that is a sentence written for a person and it is
allowed to improve.
{
"ok": false,
"detail": "that PDF is locked against copying and editing. Post it again with unlock=1 to have the lock removed first.",
"locked": "restrictions",
"opens": true,
"allows": { "print": true, "copy": false, "modify": false },
"unlock": "post again with ?unlock=1"
}Status codes#
| Code | What it means |
|---|---|
| 400 | The request was not understood — usually no source field, or one that is not the right type. The message lists what this endpoint takes. |
| 401 | No token, an expired one (they last an hour), or one whose credential has been revoked. Ask for a new token — the body says so, and carries a link to this page. |
| 402 | This account's plan does not include what was asked for. The API itself is Pro and Enterprise. |
| 403 | The credential's scopes do not cover this call — a documents:read token cannot write. |
| 404 | No such document, or no such route. A document belonging to somebody else is a 404, not a 403. |
| 405 | That path is real, and does not take that method — the Allow header says which it does. A missing path is a 404 instead, so the two are never confused. |
| 409 | The document changed underneath a versioned update — or the PDF you sent is locked against copying and editing. That one carries locked: "restrictions" and opens with no password at all: post it again with ?unlock=1. |
| 413 | The file is larger than the plan allows (512 MB on Pro and Enterprise). |
| 415 | We cannot read that kind of file. The message lists the kinds we can. |
| 422 | We could read it and it was damaged, or it was a mermaid diagram type that cannot honestly be drawn as boxes and arrows — or the PDF will not open without a password. That one carries locked: "password": send the password with unlock=1. |
| 429 | The account's daily allowance is spent. A Retry-After header says how long until it resets. |
| 507 | That would put the account over its storage. |
A real path with the wrong method is a
405, never a 404. GET
/api/v1/pdfs — which is what everybody types first, and what a
browser does if you paste the URL — used to answer "no such route" about a
route that is right there, sending people looking for a typo in a path that
was never wrong. It carries an Allow header now.Headers that carry information#
| Header | On | What it says |
|---|---|---|
Allow | on every 405 | A real path with the wrong method is a 405 naming the methods it does take — never a 404. GET /api/v1/pdfs is the one everybody types first. |
Retry-After | on 429 | Seconds until midnight UTC, when the daily allowance resets. |
X-Docubend-Warning | on .pdf | What was lossy, when something was. The body has to be a PDF and nothing else, so this is where it goes. |
X-Docubend-Dropped | on .mmd | Shapes mermaid cannot say, counted. With X-Docubend-Shapes and X-Docubend-Loose-Connectors. |