Fundamentals
Errors
Read SignatureAPI errors: HTTP status codes, the RFC 7807 problem details body, validation errors, and an index of every error type with its fix.
SignatureAPI uses conventional HTTP response codes to indicate the success or failure of an API request. In general:
- Codes in the
2XXrange indicate success. - Codes in the
4XXrange indicate problems with the request, like missing parameters. - Codes in the
5XXrange indicate problems with SignatureAPI servers.
Error messages conform to RFC 7807 and use a Content-Type of application/problem+json.
Anatomy of an error
Every error has the same parts. Branch your code on type and status. Show or log detail, but don’t parse it: its wording can change.
HTTP/1.1 401 UnauthorizedContent-Type: application/problem+json { "type": "https://signatureapi.com/docs/v1/errors/invalid-api-key", "title": "Invalid API Key", "status": 401, "detail": "Please provide a valid API key in the X-API-Key header."} - Status line The HTTP status.
4XXmeans a problem with the request;5XXmeans a problem on SignatureAPI's side. - Content type Every error body is a problem details object (RFC 7807), sent as
application/problem+json. - type A URL that identifies the problem type. Open it for the causes and the fix. Branch your code on this value.
- title A short, human-readable summary of the problem type. It is the same for every occurrence.
- status The same HTTP status code as the status line.
- detail An explanation of this occurrence. Log it, but don't parse it: the wording can change. Validation errors carry an
errorslist instead.
General Errors
This payload is for 4XX client errors, except validation errors, and 5XX errors.
A URL that identifies the problem type. Visit the URL to learn more about this problem.
A short, human-readable summary of the problem type.
The HTTP status code generated by the server for this occurrence of the problem.
A human-readable explanation specific to this occurrence of the problem.
Example
{
"type": "https://signatureapi.com/docs/v1/errors/invalid-api-key",
"title": "Invalid API Key",
"status": 401,
"detail": "Please provide a valid API key in the X-API-Key header."
}Validation Errors
This payload is for validation errors, sent with a 422 status code.
A URL that identifies the problem type. Visit the URL to learn more about this problem.
A short, human-readable summary of the problem type.
The HTTP status code generated by the server for this occurrence of the problem.
For validation errors, this value is always 422.
A human-readable list of specific validation errors.
Example
{
"type": "https://signatureapi.com/docs/v1/errors/validation-error",
"title": "Validation Error",
"status": 422,
"errors": [
"documents[0].url protocol must be HTTPS",
"recipients[0].email must be a valid email address"
]
}Retrying failed requests
A 429 response means you sent too many requests: Rate Limiting has a retry schedule and code. Most other 4XX errors fail again until you change the request. Fix the cause named in detail or errors before you retry.
Error types
Each type URL opens a page with the causes and the fix. The problem types of the public API, grouped by topic:
Authentication and mode6
invalid-401 Unauthorizedapi- key The API could not authenticate the request.
live-401 Unauthorizedmode- disabled Live API keys work only for active accounts.
live-402 Payment Requiredmode- paused Live API access for your account is paused because an invoice is still unpaid after its payment deadline.
forbidden403 ForbiddenThe resource exists, but it belongs to a different account than the API key you used.
mode-403 Forbiddenerror The requested resource (URL) exists in your account but either you are trying to access a test resource with a live API key or you are trying to access a live resource with a test API key.
mode-422 Unprocessable Contentconflict Either the client set
modetotestin a create envelope request sent with a live API key, or the client setmodetolivewith a test API key.
Request format and rate limits6
bad-400 Bad Requestrequest The server could not read the request.
not-404 Not Foundfound The requested resource (URL) could not be found on the server.
request-413 Content Too Largetoo- large The request body is larger than the API accepts.
unsupported-415 Unsupported Media Typemedia- type The API could not read the request body because of how it was encoded.
validation-422 Unprocessable Contenterror The request could not be processed because there is one or more validation errors in the body of the request.
too-429 Too Many Requestsmany- requests The client sent more requests than its rate limit allows.
Account features4
attestation-403 Forbiddennot- allowed The envelope request sets an
attestationtype that is not enabled for your account.deliverable-403 Forbiddenencryption- disabled The request sets a
passwordon a deliverable, but deliverable encryption is not enabled for your account.qualified-422 Unprocessable Contentsignature- not- enabled You created an envelope with a qualified signer, but qualified signatures are not enabled for your account.
qualified-422 Unprocessable Contentsigning- worker- not- connected You created or sent a live envelope with a qualified signer, but no active signing worker is connected for live mode.
Documents and templates10
duplicate-409 Conflictdocument- key Each document in an envelope needs a unique
key.cannot-422 Unprocessable Contentconvert The server could not convert a DOCX document to PDF.
cannot-422 Unprocessable Contentdownload- document The server could not download a document from the
urlproperty of the document in your request.cannot-422 Unprocessable Contentparse- document The file that SignatureAPI downloaded from a document's
urlcould not be read as a PDF or DOCX.cannot-422 Unprocessable Contentpopulate- template SignatureAPI could not merge the document's
datainto the DOCX document.empty-422 Unprocessable Contentdocument The file at a document's
urlis empty.invalid-422 Unprocessable Contentfield- type A conditional in a DOCX document template received a value that is not a boolean.
no-422 Unprocessable Contentpages The document was downloaded successfully but contains no pages.
template-422 Unprocessable Contenterror The server could not parse a document as a template.
too-422 Unprocessable Contentmany- pages A document has more pages than the account's page limit.
Places and placeholders15
duplicate-422 Unprocessable Contentplaceholder A placeholder text appears more than once in the document.
fixed-422 Unprocessable Contentposition- outside- document A fixed position puts a place on a
pagethat does not exist in the document.incompatible-422 Unprocessable Contentplaces A place is assigned to a recipient whose type cannot use it.
invalid-422 Unprocessable Contentplace- recipient A place has a
recipient_keythat does not match thekeyof any recipient in the envelope.invalid-422 Unprocessable Contentplaceholder The document text has a placeholder such as
[[client_signs_here]]whose name does not match thekeyof any place defined for the document.invalid-422 Unprocessable Contentplaces A place is positioned by placeholder, but the document text has no placeholder with the place's
key.missing-422 Unprocessable Contentpreset- symbol An automatic signer was assigned a
signatureorinitialsplace, but the matching image was not supplied when the envelope was created.Fix:"type": "automatic_signer", "key": "dr_doe", "name": "Dr.
mixed-422 Unprocessable Contentplaceholders The document mixes legacy signature placeholders with the newer places system.
no-422 Unprocessable Contentsigning- place A signer recipient has no
signatureorinitialsplace in any document.non-422 Unprocessable Contentexisting- place A document references a place with a key that does not exist.
place-422 Unprocessable Contentoutside- page A place in the document is positioned outside the visible page bounds.
placeholder-422 Unprocessable Contentposition- conflict A place is positioned twice: it has a fixed position in the request, and its
place_keyalso matches a placeholder in the document.too-422 Unprocessable Contentmany- places A document has more places than the account's limit.
unknown-422 Unprocessable Contentsigner A place in the document references a
recipient_keythat does not match any recipient in the envelope.unsupported-422 Unprocessable Contentrecipient- type Legacy signature placeholders only work with recipients of type
signer.
Recipients and senders9
cannot-403 Forbiddencreate- sender The request tried to create a sender through the API, but your account is not allowed to do that.
cannot-409 Conflictcreate- ceremony The request to create a ceremony failed because of the current status of the envelope or the recipient.
cannot-409 Conflictreplace The request to replace a recipient failed.
cannot-409 Conflictresend The request to resend the request email failed.
repeated-409 Conflictsender You tried to create a sender with an email address that is already in your allowed senders list.
too-409 Conflictearly- to- resend The client requested to resend a request to a recipient, but the wait period since the last send has not ended.
too-409 Conflictmany- attempts The client requested to resend a request to a recipient, but it has been sent too many times already.
blocked-422 Unprocessable Contentemail A recipient's email address is on the SignatureAPI blocklist, so the API refuses to use it.
sender-422 Unprocessable Contentnot- allowed The sender email address of an envelope must match a verified sender on the account.
Qualified signatures9
invalid-422 Unprocessable Contentqualified- attestation An envelope with a qualified signer sets an attestation.
invalid-422 Unprocessable Contentqualified- automatic- signer An automatic signer comes after the first qualified signer.
invalid-422 Unprocessable Contentqualified- deliverable- documents An envelope with a qualified signer sets
included_documentson the deliverable to only some of its documents.invalid-422 Unprocessable Contentqualified- deliverable- encryption An envelope with a qualified signer sets a deliverable password.
invalid-422 Unprocessable Contentqualified- envelope- completed- date- place An envelope with a qualified signer has an
envelope_completed_dateplace.invalid-422 Unprocessable Contentqualified- mixed- signers An envelope with a qualified signer also has a
signerrecipient.invalid-422 Unprocessable Contentqualified- places On an envelope with a qualified signer, a recipient other than the first has a place other than
signatureorinitials, such as a text input, checkbox, dropdown, or recipient name, email or date place.invalid-422 Unprocessable Contentqualified- recipient- places A qualified signer has more than one place, or a place that is not a
signatureplace.invalid-422 Unprocessable Contentqualified- routing An envelope with a qualified signer uses
parallelrouting.
Envelope and deliverable state5
deliverable-404 Not Foundnot- ready The request to download a deliverable arrived before its PDF was ready.
cannot-409 Conflictcancel The request to cancel an envelope failed because the envelope's current status does not allow it.
Fix:Read the envelope status in the
detailproperty, then act on it.cannot-409 Conflictdelete The request to delete an envelope failed because the envelope's current status does not allow it.
envelope-409 Conflictnot- completed You called Create a deliverable for an envelope whose
statusis anything other thancompleted.invalid-409 Conflictincluded- document You called Create a deliverable with an
included_documentsvalue that is not thekeyof any document in the envelope.
Uploads7
user-400 Bad Requeststorage- limit- reached Storing this upload would put your account over its storage limit for permanent uploads.
filed-409 Conflictexpired The upload you used has expired.
upload-409 Conflictalready- stored The upload has already been converted to a permanent file.
upload-409 Conflictkey- conflict The key specified in the request is already in use by another upload in your account.
cannot-422 Unprocessable Contentdownload- file SignatureAPI could not download the file from the URL in your request.
cannot-422 Unprocessable Contentparse- file SignatureAPI could not read the uploaded file as a PDF or DOCX.
invalid-422 Unprocessable Contentfile- format The server could not read the upload as a PDF or DOCX file.
No errors match your search.