Errors · Sigil Documentation

When a call fails, the response has a 4xx status and a JSON body with a single error message:

JSON

{ "error": "Sending this pact uses 1 document (one for every 3 signers) and none are left. Buy a document pack or upgrade on the Billing page." }

The message says what went wrong in a sentence you can show to the person using your app. Branch on the status code, not on the wording, which may change.

Status codes

Status	Meaning	What to do
`400` Bad Request	The request was not valid: a missing field, a bad value, a document Sigil cannot read, or an action the pact's state does not allow.	Fix the request. The message says what is wrong.
`401` Unauthorized	The API key is missing, mistyped or revoked.	Check the `Authorization` header and the key. See Authentication.
`403` Forbidden	The key is valid, but the account's plan does not include API access.	Upgrade to Pro or Business.
`404` Not Found	Nothing with that id belongs to your account, or a file is not ready yet (a signed PDF before the pact is sealed).	Check the id. Ids from another account answer `404` too.
`409` Conflict	A plan limit: not enough documents left to send. Also deleting a pact that is not a draft.	Buy a document pack, upgrade, or void instead of deleting.
`413` Content Too Large	The upload is well over 10 MB and was refused before it was read.	Send a smaller file.
`5xx`	Something failed on Sigil's side.	Retry later (see below).

Common messages

Message	Cause
`No glyphs were found. …`	The document has no glyphs. Type them in, then upload it again. See Glyphs.
`This PDF has no selectable text, so it has no glyphs. …`	The PDF is a scan or an image. Export it from the original document instead.
`The document has fields for signer 2, but only 1 signer is listed. …`	The pact lists fewer signers than the document's fields need.
`Signer 2 has nowhere to sign: …`	A signer was listed with no field in the document for them.
`That document has no fields yet. …`	The template was uploaded on the website without glyphs and its fields haven't been placed. Place them in the field editor, or upload a version with glyphs.
`"Sam Ortiz" needs a valid email address.`	A recipient's email address is missing or invalid.
`avery@example.com is listed twice.`	Each address can appear once per pact.
`'sign.example.com' is not one of your verified domains.`	`domain_host` must be a domain verified on your account.
`Only a draft can be sent.`	The pact was already sent.
`This pact is already being sent, or has been.`	Two send calls raced; the first one won.
`Only a pact that is out for signature can be voided.`	It is a draft (delete it instead) or already finished.
`Sending this pact uses … and none are left. …`	Not enough documents. See Documents and plans.

Retrying

A 4xx will fail the same way again until the request changes, so do not retry it unchanged. For a 5xx or a network failure:

Reads are safe to retry. GET calls change nothing.
Sending is protected. A pact can only be sent once: a repeated send answers 400 and charges nothing more. Get the pact to see whether the first attempt went through.
Creating is not. A retried POST /pacts can create a second pact, and with "send": true send it twice. Before retrying, list your pacts to see whether the first one exists.

Wait a little longer between each retry, and give up after a few attempts.

MCP errors

Through the MCP server, a failed tool call returns a result with isError: true whose text is An error occurred invoking '<tool>': followed by the same message, so the assistant can read it, explain it, and often fix the call itself. An invalid key or plan answers 401 or 403 before any tool runs, with the same JSON body as the API.