Skip to content

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 2XX range indicate success.
  • Codes in the 4XX range indicate problems with the request, like missing parameters.
  • Codes in the 5XX range 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.

Response
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."}
  1. Status line The HTTP status. 4XX means a problem with the request; 5XX means a problem on SignatureAPI's side.
  2. Content type Every error body is a problem details object (RFC 7807), sent as application/problem+json.
  3. type A URL that identifies the problem type. Open it for the causes and the fix. Branch your code on this value.
  4. title A short, human-readable summary of the problem type. It is the same for every occurrence.
  5. status The same HTTP status code as the status line.
  6. detail An explanation of this occurrence. Log it, but don't parse it: the wording can change. Validation errors carry an errors list instead.

General Errors

This payload is for 4XX client errors, except validation errors, and 5XX errors.

typestring

A URL that identifies the problem type. Visit the URL to learn more about this problem.

titlestring

A short, human-readable summary of the problem type.

statusinteger

The HTTP status code generated by the server for this occurrence of the problem.

detailstring

A human-readable explanation specific to this occurrence of the problem.

Example

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."
}

Validation Errors

This payload is for validation errors, sent with a 422 status code.

typestring

A URL that identifies the problem type. Visit the URL to learn more about this problem.

titlestring

A short, human-readable summary of the problem type.

statusinteger

The HTTP status code generated by the server for this occurrence of the problem.

For validation errors, this value is always 422.

errorsarray of strings

A human-readable list of specific validation errors.

Example

JSON
{
  "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:

71 errors
Authentication and mode6
  • invalid-api-key401 Unauthorized

    The API could not authenticate the request.

  • live-mode-disabled401 Unauthorized

    Live API keys work only for active accounts.

  • live-mode-paused402 Payment Required

    Live API access for your account is paused because an invoice is still unpaid after its payment deadline.

  • forbidden403 Forbidden

    The resource exists, but it belongs to a different account than the API key you used.

  • mode-error403 Forbidden

    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-conflict422 Unprocessable Content

    Either the client set mode to test in a create envelope request sent with a live API key, or the client set mode to live with a test API key.

Request format and rate limits6
  • bad-request400 Bad Request

    The server could not read the request.

  • not-found404 Not Found

    The requested resource (URL) could not be found on the server.

  • request-too-large413 Content Too Large

    The request body is larger than the API accepts.

  • unsupported-media-type415 Unsupported Media Type

    The API could not read the request body because of how it was encoded.

  • validation-error422 Unprocessable Content

    The request could not be processed because there is one or more validation errors in the body of the request.

  • too-many-requests429 Too Many Requests

    The client sent more requests than its rate limit allows.

Account features4
Documents and templates10
  • Each document in an envelope needs a unique key.

  • cannot-convert422 Unprocessable Content

    The server could not convert a DOCX document to PDF.

  • cannot-download-document422 Unprocessable Content

    The server could not download a document from the url property of the document in your request.

  • cannot-parse-document422 Unprocessable Content

    The file that SignatureAPI downloaded from a document's url could not be read as a PDF or DOCX.

  • cannot-populate-template422 Unprocessable Content

    SignatureAPI could not merge the document's data into the DOCX document.

  • empty-document422 Unprocessable Content

    The file at a document's url is empty.

  • invalid-field-type422 Unprocessable Content

    A conditional in a DOCX document template received a value that is not a boolean.

  • no-pages422 Unprocessable Content

    The document was downloaded successfully but contains no pages.

  • template-error422 Unprocessable Content

    The server could not parse a document as a template.

  • too-many-pages422 Unprocessable Content

    A document has more pages than the account's page limit.

Places and placeholders15
  • duplicate-placeholder422 Unprocessable Content

    A placeholder text appears more than once in the document.

  • fixed-position-outside-document422 Unprocessable Content

    A fixed position puts a place on a page that does not exist in the document.

  • incompatible-places422 Unprocessable Content

    A place is assigned to a recipient whose type cannot use it.

  • invalid-place-recipient422 Unprocessable Content

    A place has a recipient_key that does not match the key of any recipient in the envelope.

  • invalid-placeholder422 Unprocessable Content

    The document text has a placeholder such as [[client_signs_here]] whose name does not match the key of any place defined for the document.

  • invalid-places422 Unprocessable Content

    A place is positioned by placeholder, but the document text has no placeholder with the place's key.

  • missing-preset-symbol422 Unprocessable Content

    An automatic signer was assigned a signature or initials place, but the matching image was not supplied when the envelope was created.

    Fix:"type": "automatic_signer", "key": "dr_doe", "name": "Dr.

  • mixed-placeholders422 Unprocessable Content

    The document mixes legacy signature placeholders with the newer places system.

  • no-signing-place422 Unprocessable Content

    A signer recipient has no signature or initials place in any document.

  • non-existing-place422 Unprocessable Content

    A document references a place with a key that does not exist.

  • place-outside-page422 Unprocessable Content

    A place in the document is positioned outside the visible page bounds.

  • placeholder-position-conflict422 Unprocessable Content

    A place is positioned twice: it has a fixed position in the request, and its place_key also matches a placeholder in the document.

  • too-many-places422 Unprocessable Content

    A document has more places than the account's limit.

  • unknown-signer422 Unprocessable Content

    A place in the document references a recipient_key that does not match any recipient in the envelope.

  • unsupported-recipient-type422 Unprocessable Content

    Legacy signature placeholders only work with recipients of type signer.

Recipients and senders9
  • The request tried to create a sender through the API, but your account is not allowed to do that.

  • The request to create a ceremony failed because of the current status of the envelope or the recipient.

  • cannot-replace409 Conflict

    The request to replace a recipient failed.

  • cannot-resend409 Conflict

    The request to resend the request email failed.

  • repeated-sender409 Conflict

    You tried to create a sender with an email address that is already in your allowed senders list.

  • The client requested to resend a request to a recipient, but the wait period since the last send has not ended.

  • too-many-attempts409 Conflict

    The client requested to resend a request to a recipient, but it has been sent too many times already.

  • blocked-email422 Unprocessable Content

    A recipient's email address is on the SignatureAPI blocklist, so the API refuses to use it.

  • sender-not-allowed422 Unprocessable Content

    The sender email address of an envelope must match a verified sender on the account.

Qualified signatures9
Envelope and deliverable state5
  • The request to download a deliverable arrived before its PDF was ready.

  • cannot-cancel409 Conflict

    The request to cancel an envelope failed because the envelope's current status does not allow it.

    Fix:Read the envelope status in the detail property, then act on it.

  • cannot-delete409 Conflict

    The request to delete an envelope failed because the envelope's current status does not allow it.

  • You called Create a deliverable for an envelope whose status is anything other than completed.

  • You called Create a deliverable with an included_documents value that is not the key of any document in the envelope.

Uploads7
  • Storing this upload would put your account over its storage limit for permanent uploads.

  • filed-expired409 Conflict

    The upload you used has expired.

  • The upload has already been converted to a permanent file.

  • The key specified in the request is already in use by another upload in your account.

  • cannot-download-file422 Unprocessable Content

    SignatureAPI could not download the file from the URL in your request.

  • cannot-parse-file422 Unprocessable Content

    SignatureAPI could not read the uploaded file as a PDF or DOCX.

  • invalid-file-format422 Unprocessable Content

    The server could not read the upload as a PDF or DOCX file.