{ "error": { "code", "message" } },
and such a response is a failure if and only if it carries an error key — that test is right
even for a client that ignores the status line. An unexpected server failure may not have this
shape: treat a 5xx without an error key as an internal_error, which is retryable. code is the
contract and never changes meaning or spelling; message is prose
for a log and may be reworded.
The enum is closed, so a switch over it can be total and needs no default branch that means
“something we did not publish”. Each code says whether retrying the identical request could ever
succeed, and how to wait if so. The same table is at the root of the OpenAPI document as
x-error-codes.
| Code | HTTP | Retry? | What it means |
|---|---|---|---|
unauthenticated | 401 | no | The credential was absent, unreadable, unknown, wrong or revoked — this answer is deliberately identical for all of them, so it cannot be used to probe which keys exist. Retrying the same request changes nothing. Check the key in Settings or issue a new one. |
forbidden | 403 | no | The key is valid and the organisation’s plan does not grant what this operation does. Nothing about the credential needs to change, and it is deliberately MORE specific than 401 because the caller has already proved they hold the key. TWO SITUATIONS PRODUCE IT. (1) THE PLAN EXCLUDES THE OPERATION: POST /api/v1/templates on the Free plan, which does not include authoring templates. A template that already exists stays readable at GET /api/v1/templates; authoring one needs a plan that includes templates. (2) WE CANNOT ESTABLISH WHAT THE PLAN INCLUDES, on any operation, so nothing is granted. That one is ours rather than yours, an ordinary account does not meet it, and it means ask us. |
insufficient_scope | 403 | no | This key is scoped and does not hold the scope this operation requires — x-required-scope on the operation names it, and the WWW-Authenticate header on the refusal repeats it (RFC 6750 §3.1). ⚠️ Retrying cannot help until the key changes: an owner or admin edits its permissions under Settings → API keys, and the same key holds the new scope from its next request — no new key is needed. A key created before scopes existed carries an empty scope list, which means EVERY capability, so this refusal cannot reach an integration that was already working. |
not_found | 404 | no | No such resource — or none this key’s organisation can see, or one that has been archived, or an id that is not a uuid. Those four are one answer on purpose: “it exists but is not yours” is itself a disclosure. Do not retry; check the id against the list endpoint. |
invalid_request | 400 | no | The request is malformed, or breaks a rule about its own shape: a body that is not JSON or does not match the operation’s schema (a missing or mistyped property, a value out of range), a document that is not a PDF or a Word file we can read, a text tag that cannot be placed, an Idempotency-Key that is present but not a valid key, a query parameter outside its range, or a cursor that names nothing. The message says which, and for a body names the property path (recipients[0].email) — there is no separate param field. Fix the request; retrying it unchanged will fail identically. |
rate_limited | 429 | Exponential from 1s, doubling, with jitter. Honour Retry-After when present. | This key has spent its minute. The limit is per KEY and per minute, and it follows your PLAN rather than the kind of key — 600 requests a minute on every paid plan, 60 on the free plan, and the sandbox gets the same number as production so that an integration which passes in rehearsal passes live. Every successful authenticated response, and this one, carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds), so a client can slow down before it is made to. THREE OPERATIONS ALSO ANSWER IT FOR A REASON OF THEIR OWN. POST /api/v1/envelopes/batches costs one request per row and is refused WHOLE when its rows do not fit what is left of the key’s minute — RateLimit-Remaining says how many would. GET /api/v1/envelopes/{envelopeId}/documents/{position}/draft has its own per-envelope and per-organisation ceilings on renders each minute, and the message says which one refused; POST /api/v1/templates/{templateId}/preview shares the per-organisation one. There Retry-After is that ceiling’s, while the RateLimit-* headers still describe the key. Retry-After on this refusal is at most 60 and is read from the stored window rather than computed, so two of our instances refusing the same key quote the same instant. ⚠️ A REFUSED REQUEST STILL COUNTS: hammering a limit you have already exceeded pushes the counter higher rather than holding it. Honour Retry-After. If one key genuinely needs more throughput, issue a second one in Settings — the ceiling is a fairness and blast-radius control, not a commercial meter. |
internal_error | 500 | Exponential from 1s, at most three attempts, then stop and alert a human. | Ours, not yours. ⚠️ RETRY WITH THE SAME Idempotency-Key YOU SENT THE FIRST TIME, on any operation that takes one — that is what makes a retry safe here, and sending a NEW key would create a second envelope or send the same one twice. The safe GETs in this document can be retried freely. (This entry used to say every operation here was a GET; the write endpoints have since shipped, and the reasoning moved with them.) |
service_unavailable | 503 | Honour Retry-After when the answer carries one; otherwise exponential from 5s, doubling, for a few minutes. Nothing was created. | Ours, and briefly. Something this operation depends on was not answering, or was already doing as much as it will at once. What it was depends on the operation: on a create, the service that renders a Word document to a PDF, or the isolated service every uploaded document is read in, when it is starting up, at capacity, or did not answer in time; on GET .../documents/{position}/draft and POST /api/v1/templates/{templateId}/preview, the service that renders the draft or the preview itself; on the two template-document reads (GET /api/v1/documents/{documentId}/pages/{pageNumber} and .../content), that same isolated service, which says so with Retry-After. ⚠️ THE DISTINCTION FROM 400 IS THE WHOLE POINT: your request is fine and your document is fine, so do not go and re-save it. On a create, nothing was created and no allowance was spent. On an operation that takes an Idempotency-Key, retry the identical request with the SAME one — a completed key replays, so a retry can never make a second envelope or a second template even if the first attempt got further than this answer suggests. A new key could. ⚠️ ON THE DRAFT AND THE PREVIEW THE ATTEMPT WAS ALREADY PAID FOR: the render is charged to the per-minute draft ceilings (the envelope’s and the organisation’s, or the organisation’s alone) before the renderer is asked, and a render that then fails is not refunded. There is no key to reuse, because there is nothing to replay — so retry on the backoff above rather than at once, or an outage of ours becomes a rate_limited of yours. |
idempotency_key_required | 400 | no | Send Idempotency-Key: <uuid> — this operation takes one and the request carried none. A distinct code from invalid_request because the remedy is to ADD a header, and an integrator reading it in a log should not have to work that out. (A key that is present but malformed is invalid_request, and its message names the header.) |
idempotency_key_reused | 409 | no | This key was already used for a DIFFERENT request. ⚠️ The request itself may be perfectly valid — what conflicts is the key against state we already hold, which is what 409 means and why it is not a 400. Mint a new key. Do not retry with this one; it will conflict forever. |
request_in_progress | 409 | Exponential from 1s, up to about 30s in total. The first request is still running. | A request carrying this key has not finished. We deliberately do not block waiting for it — that would hold a connection across a send that calls an email provider N times. Retry the identical request; when the first one lands you will get its result, replayed. |
template_archived | 404 | no | The template exists and has been retired. It has a code of its own because a bare 404 tells an integrator whose template was archived yesterday nothing. It carries the same 404 status and it only ever fires for a template their own key could otherwise have read — discoverability without disclosure. Use a live template. |
template_unusable | 422 | no | The template cannot produce an envelope at all. The message says which way. |
template_has_no_fields | 422 | no | There are no fields, so the envelope would ask nobody to do anything. From a template — creating an envelope, a batch, or sending a draft made from one — place at least one field on the template in the editor; a template made from a document with text tags arrives with them already placed. On POST /api/v1/envelopes/one-off, which has no template and no editor, fields come only from text tags in the documents you send, and this is refused only when none of them places a field — an untagged annexure beside a tagged document is fine. Add a tag such as <<sig:Employee>>, naming a recipient’s role, to any of them and send it again. Nothing is detected there, and the body has no property for placing a field. A batch refuses every row for this, because every row shares the template. |
template_changed | 412 | no | The template is not the version you checked: the If-Match on a rename, or the template_etag on an envelope create, names an etag that is no longer current, or documents on an envelope create names a template document the template does not hold. Nothing was written or created. Read the template again (GET /api/v1/templates/{templateId}; a rename’s refusal also carries the current ETag), look at what changed — a rename can swap which box an address fills, and its documents lists the ids it holds now — and send again with the new etag or ids. |
template_document_not_omittable | 422 | no | documents on an envelope create left out a template document ("include": false) that the envelope cannot do without: it holds the last signature box a required role is sure to sign (and no attachment gives the role another), a box about a subject, a box that shows or hides a box on a document you kept, some options of a question a kept document also asks, or every box of a role you named a recipient for — or every template document was left out. The message names the document and the reason, and what would let it go where something would: leaving the recipient out, or an attachment tagged with the role’s signature. Otherwise keep it, or change the template; resending the same request fails the same way. Nothing was created. |
precondition_required | 428 | no | A rename needs If-Match set to the ETag of the template you read, so that it cannot overwrite a change you have not seen. * is not accepted, for the same reason. Read the template, then send its ETag. |
field_unknown | 422 | no | An id in the rename (a field’s, or a question’s) is not one of this template’s, or is not a uuid. Take ids from fields[].id and questions[].id of the template read the ETag came from. Nothing was renamed. |
naming_rule_broken | 422 | no | A name breaks a naming rule: the grammar (namespace.attribute or namespace.entity.attribute, snake_case), a core namespace, a subject key used as a namespace, an address given to a box in a question, or a collision with another field. The message names the rule and the fields. Nothing was renamed: change the names and send again. |
naming_run_not_ready | 409 | Read the run again in a minute, or wait for its template.named event. | The naming run is still queued or running, so it has nothing to accept yet. Runs are produced within a minute or two: read it with GET …/naming-runs/{runId} until its status is succeeded, or wait for template.named. Nothing was written. |
naming_run_failed | 409 | no | The naming run failed and has no proposals; its error says why. Request a new run. Nothing was written. |
proposal_changed | 409 | no | There is no proposal to accept for that person on the template as it now stands: nobody by that id was found, or the current proposal changes nothing. Read the people again (GET /api/v1/templates/{templateId}/people). Nothing was written. |
decision_not_allowed | 422 | no | That decision is not one this person can take: somebody who is not the main person, and whose part of the form asks for their own details, needs a subject, or their details would be read as the main person’s. Choose one of the person’s offered decisions. Nothing was written. |
witness_is_permanent | 409 | no | This person is a saved witness, and changing that decision removes the witness role and sets up another, which the API does not do as a side effect. Change it in the editor. Nothing was written. |
recipient_role_unknown | 422 | no | A recipient names a role the template does not declare. Read the roles from GET /api/v1/templates/{templateId} — they are matched by NAME, exactly, because a positional address breaks when a sender reorders. |
recipient_role_missing | 422 | no | A required role that has fields on it was given nobody to fill them. Every required role the template declares with work to do needs a recipient; an optional role (Role.presence) may be left out, and is, with its fields. From a send, it also means somebody who signs or approves on a draft prepared in the dashboard has no name or email yet (their name or email reads null): add them in the dashboard first. |
recipient_role_duplicated | 422 | no | Two recipients were given one role that the template does not route as cc. Everyone on a role is served the same fields and every one of them must sign, so both would answer the same boxes and the completed envelope could never be sealed. Give each person a role of their own; several cc readers may share a role. Answered by the create endpoints, naming each recipients[i].role that holds the role, and by the send endpoint for a draft saved before this was refused. |
recipient_step_partial | 422 | no | Some recipients carry a step and some do not. Give a step to every recipient, or to none and let the array decide; a missing step is never guessed. The message names a recipient with one and a recipient without. |
step_with_signing_mode | 422 | no | Steps and signing_mode were both given — step on a recipient of POST /api/v1/envelopes/one-off, or role_steps on POST /api/v1/templates. They answer the same question, who is asked when, so give one of them. |
value_subject_unknown | 422 | no | A value names a subject the template does not declare. The subjects are in the template response; null is the subject for a field belonging to nobody in particular. |
value_address_unknown | 422 | no | The (subject, key) pair addresses no field of this template. ⚠️ This is the refusal that most often means the template has UNADDRESSED boxes rather than that you mistyped: data_key is null on any field the sender never gave an address to. Check the template response before blaming the value. |
value_not_writable | 422 | no | The value cannot be written at this address. A field there is one nobody may fill in — a date_signed, a signer_name, a signature: those are written by the server or by the signer. Or a dropdown there does not offer the value. Or a lone tickbox there is given something other than "true", "false" or "". Or the value is an array, which only a question takes. Or, on a rename, a key is given to a field nobody may prefill. |
value_option_unknown | 422 | no | A value for a question names an option it does not have. The message lists the question’s options as {value, label}; send one of those values (options[].value on the question in GET /api/v1/templates/{templateId}). On a rename, an option_value outside the options a core choice key fixes. Nothing was created or renamed. |
value_option_locked | 422 | no | A value for a question disagrees with an option the template locks (questions[].options[].locked in GET /api/v1/templates/{templateId}). Either it names an option locked cleared, which the sent document leaves unticked whatever a value says; or it leaves out an option locked ticked, which the document ticks anyway, and with it the question would tick more than max_selected. A locked-ticked option left out is otherwise added for you. The message names the option and says what to send: every option locked ticked, none locked cleared, and open options within the bounds. Not raised for an entry that sets locked, which replaces the template’s locks on every box. Nothing was created. |
value_selection_out_of_bounds | 422 | no | A value for a question ticks fewer options than its min_selected or more than its max_selected, counting every option the template locks ticked whether the value names it or not. The message states the bounds and the count. Send an array of option values within them — [] for none, where min_selected is 0. |
value_not_lockable | 422 | no | The address names a signer_title or a signer_company, and locked cannot ride on a value for one. ⚠️ THE VALUE ITSELF IS FINE — send the same triple without locked and it is accepted. What is refused is FIXING the answer on the field: a title is a fact about whoever fills the slot, so it is seeded per recipient from the job_title and company you give on the recipient, while a locked answer is one value on one box — assert it and every party holding that role signs under the same title. Set job_title / company on each recipient instead. (A sender may still tick “Signer cannot change” on such a field in the editor: there the lock says the roster’s value is final and carries no answer of its own.) |
locked_answer_missing | 422 | no | A field on this envelope is locked, required and carries no answer — three statements that cannot all be honoured. A locked answer is the sender’s, so the signer is refused if they supply one and the completeness check does not ask them for it; once sent, nobody could fill the box and it would seal blank. ⚠️ THE LOCK MAY NOT HAVE COME FROM YOUR REQUEST — it can be authored on the template — so the message names the FIELD rather than a values[i] path. Send a value for that address, send {"value": "", "locked": false} to hand it back to the signer, or have the template make it optional. ⚠️ THE SAME CODE ALSO MEANS A QUESTION NOBODY LEFT COULD ANSWER. Grouped tickboxes — a Race or Gender question — are never individually required; the question’s own min_selected is what makes it compulsory. Lock every option of such a question with no tick in any of them and it asks for more answers than remain within anybody’s reach, which is the same unsatisfiable sentence and refuses the same way. There the message names the QUESTION, and the remedies are to tick one of the locked options, unlock one, or lower the question’s minimum. |
locked_answer_unusable | 422 | no | A field on this envelope carries a locked answer the field itself will not accept: a value its validation rule rejects, one its input format cannot carry, one longer than the printed cells of a comb or holding a character one of those cells does not accept, a date that is not a calendar day, or a dropdown answer that is not among the options it offers. ⚠️ A date DRAWN AS PRINTED CELLS IS MEASURED IN ITS OWN SPELLING: it holds the digits its boxes print — 15092026, not 2026-09-15 — and those digits must still name a day that exists, read in the order the field’s label states (Date of birth (DD/MM/YYYY)). ⚠️ THIS IS NOT locked_answer_missing — that one is a box with NO answer. This is a box with an answer nobody can use: a locked answer is the sender’s, the signer may not change it, and their very first save would be refused over it on an envelope nobody can edit any more. Refused here so that it is still a draft. ⚠️ THE ANSWER MAY NOT HAVE COME FROM YOUR REQUEST — a lock and its value can be authored on the template, and a rule can be tightened after the answer was fixed — so the message names the FIELD rather than a values[i] path. Send a value that satisfies the field, send {"locked": false} to hand the box back to the signer, or change the rule on the template. ⚠️ THE SAME CODE ALSO MEANS A QUESTION THE SENDER ANSWERED MORE TIMES THAN IT PERMITS, AND THEN NO FIELD RULE IS BROKEN AT ALL. Grouped tickboxes — a Marital status question at max_selected: 1 — can each carry a perfectly good locked tick while together they assert more than the question allows; every one of them would seal, side by side, on a question that says fewer can be true, and the signer may clear none of them. There the message names the QUESTION rather than a field, and sending a field-valid value resolves nothing because every value already is one. The remedies are to untick one of the locked options, to unlock one so the signer chooses, or to raise the question’s max_selected. ⚠️ AND THAT LAST ONE IS NOT SOMETHING YOU CAN SEND: max_selected is published by GET /api/v1/templates/{templateId} and NO ENDPOINT HERE SETS IT — a question’s bounds are authored on the template, and its id is a join key within that response rather than an address this API accepts. ⚠️ A QUESTION IS ANSWERED AT ITS OWN ADDRESS: its boxes have none. Send the option value you mean to the question’s data_key — {"key": "person.marital_status", "value": "married", "locked": true} — or an array of option values for a question that takes several, and only those boxes are ticked and locked. If this refusal names a question you sent several options to, send fewer. |
cannot_be_drawn | 422 | no | A value, a name or a title contains something the sealer cannot draw into the PDF, or a value has more characters than the printed boxes of a field split across several sets of them (Field.continuations). Asked BEFORE the send rather than discovered after everybody has signed. The message names which string, or for a split field which boxes, and never quotes the value. |
send_allowance_exhausted | 402 | no | ⚠️ 402, THE ONLY STATUS IN THIS API THAT NAMES MONEY. Not 403 (the credential is permitted; the plan is not) and not 429 (waiting does not help until the month turns). Upgrade the plan, or wait for the period to roll over. ⚠️ RETRYING IS POINTLESS BUT NOT HARMFUL — nothing was created, so there is no partial envelope to clean up. Only the Free plan (5 envelopes a month) is ever blocked, once that many envelopes have been sent in the month; every other plan is counted and never stopped, and a vsk_test_ key never meets this at all because a sandbox envelope consumes no allowance to exhaust. |
sms_allowance_exhausted | 402 | no | 402, for the reason send_allowance_exhausted gives. The envelope names a recipient asked for a mobile code (mobile_code), and the plan’s mobile codes for the month are used: only the Free plan, once 10 have been sent in the month. A code is counted once whether it went on WhatsApp, by SMS or both. Every other plan is charged per mobile code past its allowance and never stopped, and a code for an envelope already sent is never refused for billing. Send that recipient email_code or none instead, upgrade, or wait for the month to turn. Nothing was created. A vsk_test_ key never meets this: a test envelope sends no message. (The code keeps its name, sms_allowance_exhausted, so integrations switching on it keep working.) |
test_key_cannot_send | 403 | no | A vsk_test_ key tried a send it may not make. TWO SITUATIONS PRODUCE IT. (1) POST /api/v1/envelopes/{envelopeId}/send on an envelope a LIVE key created: sending it would email its real recipients and spend real allowance, so send it with a live key. (2) Far more often, a recipient who would be EMAILED and whose address is not one this organisation may send rehearsals to. THE RULE IS ABOUT WHO, NOT ABOUT WHETHER: a test key may email anybody who is a MEMBER of the sending organisation, and any other address that has CONFIRMED a verification link sent to it (Settings → Test recipients). Nobody else at all. So a mixed envelope — one "embedded": true signer in your application and one emailed counterparty — is fully rehearsable, provided that counterparty is on the list. An "embedded": true recipient is never checked against it, because an embedded recipient is issued no invitation and is emailed by no code path at all. ⚠️ WHY THE LIMIT EXISTS: a sandbox send consumes no billing allowance, so an unbounded one would be an unmetered way to email strangers from a free account, over a sending domain every customer shares. The message names each address that was refused. Your options are: add and verify the address; make the recipient "embedded": true; create the draft with "send": false; or send with a live key, which may email anybody. What a test key still never does is consume billing allowance or produce a sealed artefact anybody can be held to — its documents are watermarked on every page and sealed by a certificate issued for the sandbox and for nothing else, so a PDF reader reports the signature as intact and its issuer as untrusted, and everyone who receives one is told so before they can open it. |
test_key_cannot_read_documents | 403 | no | A vsk_test_ key asked GET /api/v1/envelopes/{id}/documents, or a draft render of one of them, for an envelope that is not a sandbox envelope. A test key may read the STATUS of any envelope in its organisation — that emails nobody and spends no allowance — but the documents endpoint hands over the bytes of a signed contract, and a sandbox is meant to be rehearsable without ever touching something real, and a draft is those bytes with the answers so far drawn on. Fetch this envelope’s documents with a live key, or fetch the documents of an envelope a test key created. |
test_key_cannot_edit_templates | 403 | no | A vsk_test_ key tried to rename a template’s fields. A template has no environment — one template serves test and live sends alike — so a test key’s rename would change what live envelopes contain, and a swapped address prefills the wrong box silently. Rename with a live key that names templates:name, or in the editor. |
document_too_complex | 422 | no | The document needs more memory or time to read than one document is allowed, what reading it produced is larger than one document may produce, or it could not be read through at all. Every uploaded PDF is read in an isolated service, one document at a time, under a fixed memory limit and a fixed time limit, and this one went past one of them; the message says which. Because nothing else was running there, the same document fails the same way. On an upload (POST /api/v1/templates, POST /api/v1/envelopes/one-off) nothing was stored or created; printing the document to a new PDF usually makes it simpler. On GET /api/v1/documents/{documentId}/pages/{pageNumber} or .../content, the document was stored before uploads were checked this way and its viewing copy cannot be made; the template, with every field and its position, is still readable from GET /api/v1/templates/{templateId}. Retrying gives the same answer. |
test_key_cannot_mint | 403 | no | A vsk_test_ key asked POST /api/v1/envelopes/{envelopeId}/recipients/{recipientId}/signing-url for an envelope that is not a sandbox envelope. A minted URL opens that signer’s session on the document, and on a live envelope that document is binding, so a test key may mint only on an envelope a test key created. Nothing was minted and nothing was recorded. Mint this one with a live key, or rehearse on an envelope created and sent with your test key. Retrying with the same key fails identically. |
test_key_cannot_extend | 403 | no | A vsk_test_ key asked POST /api/v1/envelopes/{envelopeId}/extend for an envelope that is not a sandbox envelope. A deadline decides how long a document stays signable, and on a live envelope that document is binding, so a test key may extend only an envelope a test key created. The deadline was not changed and nothing was recorded. Extend this one with a live key, or rehearse on an envelope created with your test key. Retrying with the same key fails identically. |
test_key_cannot_discard | 403 | no | A vsk_test_ key asked DELETE /api/v1/envelopes/{envelopeId} for an envelope that is not a sandbox envelope — one somebody made in the dashboard or with a live key, whether it is still a draft or has gone out. Deleting a draft cannot be undone, so a test key may discard only a draft a test key created. Nothing was deleted. If it is still a draft, discard it with a live key or from the dashboard. Retrying with the same key fails identically. |
test_key_cannot_void | 403 | no | A vsk_test_ key asked POST /api/v1/envelopes/{envelopeId}/void for an envelope that is not a sandbox envelope. Voiding withdraws a real, binding document from its signers and revokes their links, so a test key may void only an envelope a test key created. Nothing was voided, nothing was recorded, and the Idempotency-Key was not used. Void this one with a live key, or rehearse on an envelope created with your test key. Retrying with the same key fails identically. |
webhook_url_invalid | 422 | no | The url is not one we will POST to: it is not an absolute URL, it is not https://, it carries credentials, or its host is written as a loopback, link-local or private address (localhost, 127.0.0.1, 10.0.0.5, 169.254.169.254, [::1] and the like). Deliveries are made from inside our network, so a private address would make this API a request-forgery tool. The check reads the host as written and does not resolve a name. Answered on registration and on a PATCH that changes url. Fix the URL; retrying it unchanged fails identically. |
webhook_events_invalid | 422 | no | events is missing on a registration, empty, not an array of strings, or names a type outside the published vocabulary. ⚠️ An unknown name is REFUSED rather than accepted and silently never delivered — that is how an integrator spends a week waiting for envelope.singed. The message lists every valid name. |
webhook_brand_unknown | 422 | no | brand_id names no brand of this organisation. ⚠️ 422 and not 404 because you asked for a WEBHOOK — the brand is a property of the body that does not fit. Send null to receive every envelope in the organisation. On registration, omitting it means the same; on a PATCH, omitting it leaves the endpoint’s filter as it was. |
webhook_limit_reached | 422 | no | This organisation already holds 10 endpoints, which is the maximum: every endpoint multiplies every event into another outbound request. If you are registering one per brand, use ONE endpoint with brand_id: null and route on the brand_id every event already carries. |
api_key_owner_removed | 403 | no | The person who created this key has left the organisation, and everything the key creates or sends — an envelope, a batch, a template — is attributed to that person, who must still be a member. The key is not revoked and its reads still work, and so does managing webhooks; mint a new key from a current member and use that. |
envelope_sender_removed | 422 | no | The envelope you asked to send was created in the name of somebody who has since left the organisation. An envelope sent through the API is sent in its creator’s name — the one-off’s sender, or whoever created the key that created it — and every email its signers receive names that person, so it cannot go out in the name of somebody who is no longer here, whichever key asks. The creator is fixed when the envelope is made: create it again in the name of a current member. |
recipient_not_embedded | 422 | no | This recipient was created without "embedded": true, so they have been emailed a link and no URL can be minted for them. ⚠️ THE REMEDY IS NOT ON THIS ENDPOINT: embedding is declared when the envelope is created, because it decides how a human is reached, and an envelope that has gone out has already reached them. Create the next one with the flag set. |
recipient_not_yet_turn | 409 | Do not poll. Wait for the recipient.completed webhook for the position in front, then retry once. | An envelope in steps is holding this recipient back until everybody in an earlier step has finished. Nothing about the request is wrong and the identical call will succeed later, which is why it is a 409 rather than a 422 — the same answer Dropbox Sign gives. |
recipient_cannot_sign | 409 | no | The recipient has signed, approved, declined, or been superseded or delegated away — or another member of their signing group signed first (group_resolved). Every status that produces this has no outgoing edge, so a retry cannot help and a fresh URL would open onto the same nothing. A signature or an approval is announced by the recipient.completed webhook, and a decline that ends the envelope by envelope.declined — a member of a signing group who declines does not end it while another member can still sign. ⚠️ A group_resolved recipient gets no recipient.completed of their own: the one that fired names the member who signed. A recipient who delegated or was superseded has a replacement: read it from GET /api/v1/envelopes/{envelopeId}. |
envelope_not_sent | 422 | no | This operation needs an envelope that is out for signing, and this one is not: it is still a draft, or it is finished (completed, declined, voided or expired). Three operations answer it. Minting a signing URL: a draft has not been sent to anybody — create it with "send": true, or send it first. Voiding: a draft has nothing to withdraw, because nobody has been asked to sign it — discard it with DELETE /api/v1/envelopes/{envelopeId} instead — and a finished envelope cannot be withdrawn. Extending a deadline: a draft takes its deadline when it is created, and a finished envelope has none left to move. The message says which state it is in. ⚠️ Minting and extending also answer it for an envelope whose deadline has passed while it still shows an open status: the expiry sweep has not marked it expired yet, but it is finished all the same. ⚠️ A vsk_test_ key CAN reach an open envelope: it may send one when everybody it would email is a member of your organisation or a confirmed test recipient, and an "embedded": true recipient is never emailed, so is never checked. A test key meets this code for the same reasons a live key does — most often, a draft that was never sent — except that on an envelope a test key did not create, minting is refused first with test_key_cannot_mint, extending with test_key_cannot_extend and voiding with test_key_cannot_void. |
deadline_not_extendable | 422 | no | The envelope is out for signing, but its deadline cannot be moved to the one you asked for: it has no deadline at all, so there is nothing to extend, or expires_at is not later than the deadline it has now. A deadline can be extended, never shortened. The message says which, and gives the current deadline; read it from GET /api/v1/envelopes/{envelopeId} and ask for a later one. |
envelope_not_draft | 409 | no | Only a draft can be sent, and this envelope has already left draft — through this API, through the sender’s own Send button, or by being voided. ⚠️ THE EXACT OPPOSITE OF envelope_not_sent, and the two are not interchangeable: that one means the envelope has NOT gone out. An envelope never returns to draft, so this is terminal — read it with GET /api/v1/envelopes/{envelopeId} to see where it got to. ⚠️ If you were retrying a request that timed out, send the SAME Idempotency-Key instead and you will be told what the first attempt did. ⚠️ Discarding answers it too: DELETE /api/v1/envelopes/{envelopeId} deletes only a draft, so an envelope that has gone out is refused with this code and left as it was. Withdraw a sent or partially_signed one with POST /api/v1/envelopes/{envelopeId}/void instead; a finished one has nothing left to withdraw. The message says which state it is in. |
brand_has_no_embed_origins | 422 | no | The brand has no embedding origins registered, so a signing URL for it could not be framed by anything — and an embedded recipient is never emailed, so they would be unreachable. Register the domains you embed on against that brand in Settings; they must be bare origins (https://example.com, no trailing slash and no path). ⚠️ THE BRAND IS THE ONE THE ENVELOPE GOES OUT UNDER — the brand_id you sent, or the organisation’s default when you sent none. It is NOT always the default: registering an origin against the default while sending under another brand is the mistake this refusal most often means. |
embed_origin_not_registered | 422 | no | The embed_origin you sent is not one of the origins registered against the brand this envelope was sent under, so a browser would refuse to frame the signing page there and the signer would see a blank frame. Nothing was minted and nothing was recorded. Add the origin — in Settings → Brands, or with POST /api/v1/brands/{brandId}/embed-origins from a key holding brands:write — then mint again. The message names the origin and the brand. ⚠️ It must be a bare origin — scheme, lowercase host and optional port, no trailing slash — which is what window.location.origin reports; an explicit :443 matches the same origin without it. |
recipient_cannot_be_embedded | 422 | no | A recipient was declared "embedded": true on a role the template routes as cc. A copied-in reader is never asked to sign and is never issued a signing credential, so an embedded one could be reached by nothing at all — no email, and no URL. Either drop the flag, or give the role a routing type that signs, in the template editor. |
recipient_verification_unavailabledefined, not emitted today | 422 | no | A recipient asked for a verification_method that is published and not offered yet. Every method published today is offered, so this is reserved for the next one to arrive the same way. The message names the recipient; nothing was created. |
recipient_mobile_unused | 422 | no | A recipient carried a mobile, and their verification_method sends nothing to a mobile number. It is refused rather than dropped, because a number you sent being silently discarded would be a surprise, and rather than stored, because keeping a person’s phone number for no purpose is the thing not to do with it. Leave it out, or send null. |
recipient_mobile_required | 422 | no | A recipient asked for mobile_code and carried no mobile, so there is nowhere to send the code. Send their South African mobile number. The message names the recipient; nothing was created. |
recipient_mobile_invalid | 422 | no | A recipient’s mobile is not a mobile number a code can be sent to — too short, too long, letters, or a landline, toll-free or share-call number. Send it as +27821234567, 27821234567, 082 123 4567 or 0821234567. Nothing was created. |
recipient_mobile_unsupported_country | 422 | no | A recipient’s mobile is a valid number outside South Africa. Mobile codes can be sent only to South African (+27) mobiles for now. Use email_code or none for that recipient. Nothing was created. |
recipient_verification_not_allowed | 422 | no | A recipient was asked for a code they could never be asked for: email_code on an embedded recipient, who is never emailed by Vumasign — your application authenticated them — or any code on a role routed as cc, a copied-in reader who never opens a signing page. Use none for both. In a batch the message names the row, and nothing in the batch was created. |
identity_check_requires_paid_plan | 402 | no | 402, for the reason send_allowance_exhausted gives. A recipient is asked for identity_check, and the organisation is on Free, where it is not offered — or pays by card and has no card on file to add the check to. Raised when the envelope is created and again at send. Choose another verification_method, or change plan (or add a card) in Settings, Plan and usage. Nothing was created or sent. |
identity_check_not_live | 403 | no | A LIVE envelope names identity_check, and identity checks are not switched on for live envelopes on this deployment yet. Send it with a vsk_test_ key (VerifyNow’s sandbox, at no cost), or choose another verification_method for the live envelope. Raised at send; nothing was sent. |
recipient_identity_check_not_allowed | 422 | no | identity_check on a recipient who cannot take one: a role routed as cc, or any row of a batch (an identity check is chosen per signer, one envelope at a time). Use mobile_code, or send the envelope on its own. Nothing was created. |
recipient_identity_routes_invalid | 422 | no | identity_check.routes is not either, sa_id or passport, or identity_check was sent with a verification_method other than identity_check. Nothing was created. |
recipient_expected_id_invalid | 422 | no | identity_check.expected_id cannot be used: an SA ID number that is not 13 digits, fails the checksum, has no real date of birth or a citizenship digit other than 0, 1 or 2; a passport number that is not 5 to 15 letters and digits; a missing or malformed passport country; or a kind routes rules out (an SA ID number with passport, a passport number with sa_id). The number is never quoted back. Nothing was created. |
batch_interrupted | 409 | Do not retry the batch. Retry the individual envelope this row names, with POST /api/v1/envelopes/{envelopeId}/send and its own Idempotency-Key. Immediately is fine; that endpoint refuses a second send by itself. | ⚠️ THIS CODE APPEARS INSIDE A 207 BODY, ON THE ROW IT IS ABOUT, AND NEVER ON A STATUS LINE. It means our own request died partway through a bulk send and you are being shown the batch as it actually stands: the envelopes that went out are sent, and this one is a draft that never was. It already carries its recipients and its values, so nothing needs rebuilding — send it. ⚠️ RETRYING THE BATCH IS THE WRONG MOVE: under the same key you are replayed this same answer, and under a new key you get a second hundred envelopes. |
brand_unknown | 422 | no | brand_id names no live brand of your organisation — it may belong to another account, or have been archived. Read the ids from Settings, or omit the field to send under the default. ⚠️ IT IS REFUSED RATHER THAN IGNORED because the branding an envelope went out under is frozen the moment it is sent: a wrong constant would put somebody else’s letterhead on every envelope you send, permanently, and nothing else would say so. (The product’s own send screen falls through to the default instead, because there the id came from a list a person was shown rather than from a program.) |
brand_is_archived | 409 | no | The brand is archived, so its embedding origins cannot be changed. It is still readable — GET /api/v1/brands/{brandId} returns it with its archived_at — and envelopes already sent under it keep the origins it has. Nothing was changed. Retrying cannot help: an archived brand stays archived. |
embed_origin_limit_reached | 422 | no | The brand already holds 20 embedding origins, the most one brand may. Every one of them is sent in a header on every embedded signing page, so the list is bounded. Remove one you no longer embed on with DELETE /api/v1/brands/{brandId}/embed-origins, then add again. Nothing was changed. |
test_key_cannot_edit_brands | 403 | no | A vsk_test_ key tried to change a brand’s embedding origins. A brand has no environment — one brand serves test and live sends alike — so an origin a test key added would frame live signing pages. Nothing was changed. Use a live key that names brands:write, or Settings → Brands. |
draft_not_available | 422 | no | There is no draft of this envelope to render, and the message says which of the two reasons it is. Either it is still a DRAFT — nobody has been asked to do anything, so the render would be your original document with nothing written on it — or it has already SEALED, and the final executed copy exists. ⚠️ ONE CODE FOR BOTH BECAUSE THE NEXT REQUEST IS THE SAME ONE: GET /api/v1/envelopes/{envelopeId}/documents serves the original in the first case and the sealed copy in the second. What differs is what you do with it — send the envelope, or take the executed contract — and that is what the sentence tells you. Retrying cannot help in either case: a sealed envelope never unseals, and a draft stays a draft until somebody sends it. ⚠️ A VOIDED, DECLINED OR EXPIRED envelope is NOT refused here — a contract that died part-signed is exactly the thing this endpoint exists to hand you. |
standing_authorisations_not_enabled | 403 | no | Standing authorisations are switched off for this environment of your organisation. They are on for sandbox and live in every organisation unless Vumasign has switched one off, so a test key and a live key can get different answers. Retrying changes nothing; ask us to switch the environment you need back on. A request with witness: true gets the same answer while witness use, which is switched separately, is off for that environment: it is on for sandbox, and an owner or admin of your organisation switches it on for live, in Settings › Authorisations. |
authorisation_text_rejected | 422 | no | A text you supplied breaks the mandate’s text rules: it must be one line, with no links, no control characters and not naming Vumasign, and the intended use also refuses a bare domain. The brand’s and your organisation’s names are held to the same rules because the mandate prints them; rename the brand in the dashboard if it is the brand’s name. The message names the field. |
authorisation_validity_invalid | 422 | no | The validity window or the invite lifetime is out of bounds. Check valid_from, valid_until and invite_expires_at against the limits on the request, and send again with a new Idempotency-Key. |
authorisation_not_revocable | 409 | no | Only an active authorisation can be revoked. An invited request is withdrawn with POST /api/v1/standing-authorisations/{authorisationId}/cancel; an authorisation that has already ended needs nothing more. |
authorisation_not_pending | 409 | no | The request is no longer invited, or its grantor has already signed. A signed request cannot be cancelled: wait for authorisation.granted, then revoke it. Read the authorisation for its current status. |
authorisation_resend_limited | 429 | Wait until the oldest resend in the window is 24 hours old. | The grantor has been sent a fresh link 3 times in the last 24 hours. If the address is wrong, cancel the request and send a new one instead. |
authorisation_not_renewable | 409 | no | Only an active or expired authorisation can be renewed. A revoked or invalidated one cannot: request a new one with POST /api/v1/standing-authorisations/invitations. An invited one has not been granted yet. |
authorisation_already_renewed | 409 | no | A renewal of this authorisation is already pending or has taken effect; the message names it. List with status to find it, and renew that one when its turn comes. A renewal that never took effect (declined, lapsed unsigned or cancelled) does not count. |
authorisation_unknown | 422 | no | The authorisation_id names no standing authorisation of your organisation. A test key cannot see a live authorisation and gets this answer for one: apply a sandbox authorisation with a test key, and a live one with a live key. |
authorisation_not_granted | 422 | no | The authorisation was never in force: it is still invited, or it was declined, lapsed unsigned or was cancelled. Wait for authorisation.granted, or request a new one. |
authorisation_revoked | 422 | no | The authorisation has been revoked. Documents already sent under it keep the signature applied when they were sent; this one cannot be pre-signed. Name another authorisation, or have a person sign the role. |
authorisation_expired | 422 | no | The authorisation’s valid_until has passed, by the database’s clock, whatever its status last said. Renewal is a new mandate: request one. |
authorisation_not_yet_valid | 422 | Wait until the authorisation’s valid_from has passed. | The authorisation runs from a valid_from that has not yet arrived. Send the document after it does. |
authorisation_invalidated | 422 | no | The authorisation ended because its brand’s name, email display name or logo changed, or the brand was archived, after it was granted. This is final: request a new mandate under the brand as it is now. |
authorisation_brand_mismatch | 422 | no | The document goes out under a different brand from the authorisation’s, or under no brand. Send brand_id naming the authorisation’s brand on every create, batch and one-off. |
authorisation_environment_mismatch | 422 | no | A live document names a sandbox authorisation. A sandbox authorisation pre-signs only sandbox documents (made with a test key), and a live one only live documents. |
authorisation_role_is_witness | 422 | no | The role witnesses a signature: the template marks it witness, or its name contains “witness” or “getuie” anywhere, in any case. A standing authorisation pre-signs a witness role only when its mandate was requested with witness: true AND witness use is enabled for this environment of your organisation; the message says which is missing. Have a person sign that role, or use an authorisation granted for witness use. |
authorisation_role_not_signing | 422 | no | The role approves or is copied in, so there is nothing to pre-sign. Name the authorisation on a role that signs. |
authorisation_recipient_altered | 422 | no | The pre-signed recipient on this draft no longer matches its authorisation’s grantor, so it was edited after it was named. Name the authorisation on the role again rather than editing the recipient. |
authorisation_used_twice | 422 | no | The same authorisation is named on more than one role of one document. One authorisation pre-signs one role per document; two roles need two authorisations, held by two people. |
authorisation_grantor_twice | 422 | no | One person would sign the document twice. Either two different authorisations on one document have the same grantor: one person’s signature may cover one role per document, so name one of them and have the person sign the other capacity themselves. Or a witness role is pre-signed under an authorisation whose grantor is also a recipient who signs or approves any document of the envelope: nobody witnesses their own signature, so have someone else sign that recipient’s role, or a different person witness. |
authorisation_field_unsupported | 422 | no | The pre-signed role carries a field it cannot: an initial, an attachment, an email tag (it would print the grantor’s address on the document), or a field that shows or hides depending on another answer or on who the document is about. Remove it from the role. |
authorisation_value_forbidden | 422 | no | A value was supplied for the pre-signed role’s title or company. Vumasign fills both from the authorisation (the capacity signed on the mandate, and the legal entity). Leave them out of values. |
value_for_left_out_role | 422 | no | A value was supplied for a field of an optional role the request gives nobody. That role is left out when the envelope is sent, and its fields are removed with it, so the value would land nowhere. Give the role a recipient, or leave its fields out of values. |
authorisation_value_missing | 422 | no | A required text, date, checkbox or dropdown field of the pre-signed role has no value. Supply each one in values with "locked": true: a mandate applies a signature and never chooses an answer. An optional one you leave out is sealed blank. A one-off takes no values, so every required field of its pre-signed role must be one Vumasign fills. |
authorisation_value_unlocked | 422 | no | A value for the pre-signed role was supplied without "locked": true. Send it again locked. |
authorisation_mark_too_small | 422 | no | A signature box of the pre-signed role is too small to carry its caption, the authorisation’s number (“SA-0012”), beside a signature. The number stands on the frame’s bottom rule after the envelope reference where the box is wide enough, and under the frame where it is not. Make the box larger: a party role’s box needs at least 76.32 by 18.88pt (beside the envelope reference) or 39.44 by 20.85pt (under the frame, on one line); a witness role’s, whose caption is “SA-0012 · not present”, needs at least 109.11 by 19.02pt (beside the envelope reference), 72.24 by 20.85pt (under the frame, on one line), 48.16 by 26.10pt (under the frame, on two lines) or 42.22 by 31.35pt (under the frame, on three lines). Each digit of the number past four adds at most 3.003pt of width. |
authorisation_mark_unplaced | 422 | no | The pre-signed role has no signature box on the document, so its signature and the caption that says it was applied under a standing authorisation would appear nowhere on the page. Give the role a signature tag, or let a person sign it. |
authorisation_mark_unavailable | 503 | Retry once after a minute; if it persists, contact Vumasign. | The grantor’s stored signature could not be read intact, so nothing was applied. A brief storage failure clears on a retry; one that persists means the stored signature no longer matches what was granted, and needs Vumasign. |
authorisation_expires_during_batch | 422 | no | A batch names an authorisation that ends too soon for every row to be sent under it, so the batch was refused before any row was sent: a batch never goes out half pre-signed and half refused. Send it under an authorisation with more time left, or after renewing it. |
Retrying a request safely
These operations require anIdempotency-Key:
POST /api/v1/templatesPOST /api/v1/templates/{templateId}/naming-runsPOST /api/v1/envelopesPOST /api/v1/envelopes/one-offPOST /api/v1/envelopes/batchesPOST /api/v1/envelopes/{envelopeId}/voidPOST /api/v1/envelopes/{envelopeId}/extendPOST /api/v1/envelopes/{envelopeId}/sendPOST /api/v1/standing-authorisations/{authorisationId}/cancelPOST /api/v1/standing-authorisations/{authorisationId}/resendPOST /api/v1/standing-authorisations/{authorisationId}/revokePOST /api/v1/standing-authorisations/{authorisationId}/renewPOST /api/v1/standing-authorisations/invitations
DELETE takes no key, because repeating one cannot do anything twice. A retry of a
DELETE /api/v1/envelopes/{envelopeId} or a
DELETE /api/v1/webhooks/{webhookId} whose first attempt took
effect is answered not_found: the thing is already gone.
The key identifies one request, not one envelope: generate a key for each request you intend,
store it before the first attempt, and reuse it only to retry that same request with the identical
body. Creating a draft and then sending it are separate requests, each with its own key; a key
already used for one is refused for the other as idempotency_key_reused, and so is the same key
with a different body. A retry while the first attempt is still running is answered
request_in_progress: retry the identical request under the backoff the table above
gives for that code.
Within the key’s retention window, which the create-envelope reference
states, a retry returns the first attempt’s answer and does nothing again. Past the window the
key can be forgotten at any time, and a request carrying it is then a new request:
- A send that already went out is refused as
envelope_not_draft, and a void that already took effect is refused asenvelope_not_sent. A late retry of either changes nothing. - A late retry of a request that creates something is not harmless: it can create it again — a second template, envelope or batch, and an envelope that is sent emails its recipients again.
- For a template, the template list is newest first and each row
carries
id,nameandcreated_at. Look for one created around your first attempt under the name it was given. - For an envelope, set
referenceon every envelope you create — onPOST /api/v1/envelopes, on a one-off, and on each row of a batch — and store it before the first attempt, beside the idempotency key. Past the window, ask the envelope list with?reference=and the value you sent. A row means the first attempt created that envelope; an empty page means it did not. The reference is compared in Unicode NFC whichever form you send, and it cannot be changed after creation, so it still names the envelope when you come back for it. - The API does not make a
referenceunique: it accepts one value on any number of envelopes, and the list returns every match, newest first. For exactly one envelope per reference, derive it from the record in your system that asked for the envelope — not from the attempt — and never reuse it. - Each row carries
id,title,status,template_id,reference,created_atandsent_at— no recipients.?reference=combines withstatusandcursor. - For an envelope created without a reference, the list cannot be searched by your own
identifiers. Narrow it to rows with the
template_idyou sent (nullfor a one-off) created around your first attempt, read each candidate withGET /api/v1/envelopes/{envelopeId}, and match its recipients on theemailand theexternal_refyou sent.external_refis stored NFC-normalised, so normalise your own value to NFC before comparing.