---
title: "Errors"
description: "Read SignatureAPI errors: HTTP status codes, the RFC 7807 problem details body, validation errors, and an index of every error type with its fix."
canonical: "https://signatureapi.com/docs/api/errors"
source: "https://signatureapi.com/docs/api/errors.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T11:48:47Z"
---

# 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.

_Last verified against API version 1.18.0._

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](https://datatracker.ietf.org/doc/html/rfc7807) 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
HTTP/1.1 401 Unauthorized
Content-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** (line 1: `HTTP/1.1 401 Unauthorized`): The HTTP status. `4XX` means a problem with the request; `5XX` means a problem on SignatureAPI's side.
2. **Content type** (line 2: `Content-Type: application/problem+json`): Every error body is a problem details object (RFC 7807), sent as `application/problem+json`.
3. **type** (line 5: `"type": "https://signatureapi.com/docs/v1/errors/invalid-api-key",`): A URL that identifies the problem type. Open it for the causes and the fix. Branch your code on this value.
4. **title** (line 6: `"title": "Invalid API Key",`): A short, human-readable summary of the problem type. It is the same for every occurrence.
5. **status** (line 7: `"status": 401,`): The same HTTP status code as the status line.
6. **detail** (line 8: `"detail": "Please provide a valid API key in the X-API-Key header."`): 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.

#### `type` (string)

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

#### `title` (string)

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

#### `status` (integer)

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

#### `detail` (string)

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.

#### `type` (string)

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

#### `title` (string)

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

#### `status` (integer)

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

For validation errors, this value is always `422`.

#### `errors` (array 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](https://signatureapi.com/docs/api/rate-limiting#handling-rate-limits) 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 mode**

- [Invalid API Key](https://signatureapi.com/docs/v1/errors/invalid-api-key) (`invalid-api-key`, HTTP 401): The API could not authenticate the request.
- [Live Mode Disabled](https://signatureapi.com/docs/v1/errors/live-mode-disabled) (`live-mode-disabled`, HTTP 401): Live API keys work only for active accounts.
- [Live Mode Paused](https://signatureapi.com/docs/v1/errors/live-mode-paused) (`live-mode-paused`, HTTP 402): Live API access for your account is paused because an invoice is still unpaid after its payment deadline.
- [Forbidden](https://signatureapi.com/docs/v1/errors/forbidden) (`forbidden`, HTTP 403): The resource exists, but it belongs to a different account than the API key you used.
- [Test/Live Mode Error](https://signatureapi.com/docs/v1/errors/mode-error) (`mode-error`, HTTP 403): 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.
- [Test/Live Mode Conflict](https://signatureapi.com/docs/v1/errors/mode-conflict) (`mode-conflict`, HTTP 422): 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 limits**

- [Bad Request](https://signatureapi.com/docs/v1/errors/bad-request) (`bad-request`, HTTP 400): The server could not read the request.
- [Not Found](https://signatureapi.com/docs/v1/errors/not-found) (`not-found`, HTTP 404): The requested resource (URL) could not be found on the server.
- [Request Too Large](https://signatureapi.com/docs/v1/errors/request-too-large) (`request-too-large`, HTTP 413): The request body is larger than the API accepts.
- [Unsupported Media Type](https://signatureapi.com/docs/v1/errors/unsupported-media-type) (`unsupported-media-type`, HTTP 415): The API could not read the request body because of how it was encoded.
- [Validation Error](https://signatureapi.com/docs/v1/errors/validation-error) (`validation-error`, HTTP 422): The request could not be processed because there is one or more validation errors in the body of the request.
- [Too Many Requests](https://signatureapi.com/docs/v1/errors/too-many-requests) (`too-many-requests`, HTTP 429): The client sent more requests than its rate limit allows.

**Account features**

- [Attestation Not Allowed](https://signatureapi.com/docs/v1/errors/attestation-not-allowed) (`attestation-not-allowed`, HTTP 403): The envelope request sets an attestation type that is not enabled for your account.
- [Deliverable Encryption Disabled](https://signatureapi.com/docs/v1/errors/deliverable-encryption-disabled) (`deliverable-encryption-disabled`, HTTP 403): The request sets a password on a deliverable, but deliverable encryption is not enabled for your account.
- [Qualified Signature Not Enabled](https://signatureapi.com/docs/v1/errors/qualified-signature-not-enabled) (`qualified-signature-not-enabled`, HTTP 422): You created an envelope with a qualified signer, but qualified signatures are not enabled for your account.
- [Qualified Signing Worker Not Connected](https://signatureapi.com/docs/v1/errors/qualified-signing-worker-not-connected) (`qualified-signing-worker-not-connected`, HTTP 422): You created or sent a live envelope with a qualified signer, but no active signing worker is connected for live mode.

**Documents and templates**

- [Duplicate Document Key](https://signatureapi.com/docs/v1/errors/duplicate-document-key) (`duplicate-document-key`, HTTP 409): Each document in an envelope needs a unique key.
- [Cannot Convert](https://signatureapi.com/docs/v1/errors/cannot-convert) (`cannot-convert`, HTTP 422): The server could not convert a DOCX document to PDF.
- [Cannot Download Document](https://signatureapi.com/docs/v1/errors/cannot-download-document) (`cannot-download-document`, HTTP 422): The server could not download a document from the url property of the document in your request.
- [Cannot Parse Document](https://signatureapi.com/docs/v1/errors/cannot-parse-document) (`cannot-parse-document`, HTTP 422): The file that SignatureAPI downloaded from a document's url could not be read as a PDF or DOCX.
- [Cannot Populate Template](https://signatureapi.com/docs/v1/errors/cannot-populate-template) (`cannot-populate-template`, HTTP 422): SignatureAPI could not merge the document's data into the DOCX document.
- [Empty Document](https://signatureapi.com/docs/v1/errors/empty-document) (`empty-document`, HTTP 422): The file at a document's url is empty.
- [Invalid Field Type](https://signatureapi.com/docs/v1/errors/invalid-field-type) (`invalid-field-type`, HTTP 422): A conditional in a DOCX document template received a value that is not a boolean.
- [No Pages](https://signatureapi.com/docs/v1/errors/no-pages) (`no-pages`, HTTP 422): The document was downloaded successfully but contains no pages.
- [Template Error](https://signatureapi.com/docs/v1/errors/template-error) (`template-error`, HTTP 422): The server could not parse a document as a template.
- [Too Many Pages](https://signatureapi.com/docs/v1/errors/too-many-pages) (`too-many-pages`, HTTP 422): A document has more pages than the account's page limit.

**Places and placeholders**

- [Duplicate Placeholder](https://signatureapi.com/docs/v1/errors/duplicate-placeholder) (`duplicate-placeholder`, HTTP 422): A placeholder text appears more than once in the document.
- [Fixed Position Outside Document](https://signatureapi.com/docs/v1/errors/fixed-position-outside-document) (`fixed-position-outside-document`, HTTP 422): A fixed position puts a place on a page that does not exist in the document.
- [Incompatible Places](https://signatureapi.com/docs/v1/errors/incompatible-places) (`incompatible-places`, HTTP 422): A place is assigned to a recipient whose type cannot use it.
- [Invalid Place Recipient](https://signatureapi.com/docs/v1/errors/invalid-place-recipient) (`invalid-place-recipient`, HTTP 422): A place has a recipient_key that does not match the key of any recipient in the envelope.
- [Invalid Placeholder](https://signatureapi.com/docs/v1/errors/invalid-placeholder) (`invalid-placeholder`, HTTP 422): The document text has a placeholder such as [[clientsignshere]] whose name does not match the key of any place defined for the document.
- [Invalid Places](https://signatureapi.com/docs/v1/errors/invalid-places) (`invalid-places`, HTTP 422): A place is positioned by placeholder, but the document text has no placeholder with the place's key.
- [Missing Preset Symbol](https://signatureapi.com/docs/v1/errors/missing-preset-symbol) (`missing-preset-symbol`, HTTP 422): An automatic signer was assigned a signature or initials place, but the matching image was not supplied when the envelope was created.
- [Mixed Placeholders](https://signatureapi.com/docs/v1/errors/mixed-placeholders) (`mixed-placeholders`, HTTP 422): The document mixes legacy signature placeholders with the newer places system.
- [No Signing Place](https://signatureapi.com/docs/v1/errors/no-signing-place) (`no-signing-place`, HTTP 422): A signer recipient has no signature or initials place in any document.
- [Non Existing Place](https://signatureapi.com/docs/v1/errors/non-existing-place) (`non-existing-place`, HTTP 422): A document references a place with a key that does not exist.
- [Place Outside Page](https://signatureapi.com/docs/v1/errors/place-outside-page) (`place-outside-page`, HTTP 422): A place in the document is positioned outside the visible page bounds.
- [Placeholder Position Conflict](https://signatureapi.com/docs/v1/errors/placeholder-position-conflict) (`placeholder-position-conflict`, HTTP 422): 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 Places](https://signatureapi.com/docs/v1/errors/too-many-places) (`too-many-places`, HTTP 422): A document has more places than the account's limit.
- [Unknown Signer](https://signatureapi.com/docs/v1/errors/unknown-signer) (`unknown-signer`, HTTP 422): A place in the document references a recipient_key that does not match any recipient in the envelope.
- [Unsupported Recipient Type](https://signatureapi.com/docs/v1/errors/unsupported-recipient-type) (`unsupported-recipient-type`, HTTP 422): Legacy signature placeholders only work with recipients of type signer.

**Recipients and senders**

- [Could Not Create Sender](https://signatureapi.com/docs/v1/errors/cannot-create-sender) (`cannot-create-sender`, HTTP 403): The request tried to create a sender through the API, but your account is not allowed to do that.
- [Could Not Create Ceremony](https://signatureapi.com/docs/v1/errors/cannot-create-ceremony) (`cannot-create-ceremony`, HTTP 409): The request to create a ceremony failed because of the current status of the envelope or the recipient.
- [Cannot Replace](https://signatureapi.com/docs/v1/errors/cannot-replace) (`cannot-replace`, HTTP 409): The request to replace a recipient failed.
- [Cannot Resend](https://signatureapi.com/docs/v1/errors/cannot-resend) (`cannot-resend`, HTTP 409): The request to resend the request email failed.
- [Repeated Sender](https://signatureapi.com/docs/v1/errors/repeated-sender) (`repeated-sender`, HTTP 409): You tried to create a sender with an email address that is already in your allowed senders list.
- [Too Early to Resend](https://signatureapi.com/docs/v1/errors/too-early-to-resend) (`too-early-to-resend`, HTTP 409): The client requested to resend a request to a recipient, but the wait period since the last send has not ended.
- [Too Many Attempts](https://signatureapi.com/docs/v1/errors/too-many-attempts) (`too-many-attempts`, HTTP 409): The client requested to resend a request to a recipient, but it has been sent too many times already.
- [Blocked Recipient Email](https://signatureapi.com/docs/v1/errors/blocked-email) (`blocked-email`, HTTP 422): A recipient's email address is on the SignatureAPI blocklist, so the API refuses to use it.
- [Sender Not Allowed](https://signatureapi.com/docs/v1/errors/sender-not-allowed) (`sender-not-allowed`, HTTP 422): The sender email address of an envelope must match a verified sender on the account.

**Qualified signatures**

- [Invalid Qualified Attestation](https://signatureapi.com/docs/v1/errors/invalid-qualified-attestation) (`invalid-qualified-attestation`, HTTP 422): An envelope with a qualified signer sets an attestation.
- [Invalid Qualified Automatic Signer](https://signatureapi.com/docs/v1/errors/invalid-qualified-automatic-signer) (`invalid-qualified-automatic-signer`, HTTP 422): An automatic signer comes after the first qualified signer.
- [Invalid Qualified Deliverable Documents](https://signatureapi.com/docs/v1/errors/invalid-qualified-deliverable-documents) (`invalid-qualified-deliverable-documents`, HTTP 422): An envelope with a qualified signer sets included_documents on the deliverable to only some of its documents.
- [Invalid Qualified Deliverable Encryption](https://signatureapi.com/docs/v1/errors/invalid-qualified-deliverable-encryption) (`invalid-qualified-deliverable-encryption`, HTTP 422): An envelope with a qualified signer sets a deliverable password.
- [Invalid Qualified Envelope Completed Date Place](https://signatureapi.com/docs/v1/errors/invalid-qualified-envelope-completed-date-place) (`invalid-qualified-envelope-completed-date-place`, HTTP 422): An envelope with a qualified signer has an envelopecompleteddate place.
- [Invalid Qualified Mixed Signers](https://signatureapi.com/docs/v1/errors/invalid-qualified-mixed-signers) (`invalid-qualified-mixed-signers`, HTTP 422): An envelope with a qualified signer also has a signer recipient.
- [Invalid Qualified Places](https://signatureapi.com/docs/v1/errors/invalid-qualified-places) (`invalid-qualified-places`, HTTP 422): On an envelope with a qualified signer, a recipient other than the first has a place other than signature or initials, such as a text input, checkbox, dropdown, or recipient name, email or date place.
- [Invalid Qualified Recipient Places](https://signatureapi.com/docs/v1/errors/invalid-qualified-recipient-places) (`invalid-qualified-recipient-places`, HTTP 422): A qualified signer has more than one place, or a place that is not a signature place.
- [Invalid Qualified Routing](https://signatureapi.com/docs/v1/errors/invalid-qualified-routing) (`invalid-qualified-routing`, HTTP 422): An envelope with a qualified signer uses parallel routing.

**Envelope and deliverable state**

- [Deliverable Not Ready](https://signatureapi.com/docs/v1/errors/deliverable-not-ready) (`deliverable-not-ready`, HTTP 404): The request to download a deliverable arrived before its PDF was ready.
- [Cannot Cancel](https://signatureapi.com/docs/v1/errors/cannot-cancel) (`cannot-cancel`, HTTP 409): The request to cancel an envelope failed because the envelope's current status does not allow it.
- [Cannot Delete](https://signatureapi.com/docs/v1/errors/cannot-delete) (`cannot-delete`, HTTP 409): The request to delete an envelope failed because the envelope's current status does not allow it.
- [Envelope Is Not Completed](https://signatureapi.com/docs/v1/errors/envelope-not-completed) (`envelope-not-completed`, HTTP 409): You called Create a deliverable for an envelope whose status is anything other than completed.
- [Invalid Included Document](https://signatureapi.com/docs/v1/errors/invalid-included-document) (`invalid-included-document`, HTTP 409): You called Create a deliverable with an included_documents value that is not the key of any document in the envelope.

**Uploads**

- [User Storage Limit Reached](https://signatureapi.com/docs/v1/errors/user-storage-limit-reached) (`user-storage-limit-reached`, HTTP 400): Storing this upload would put your account over its storage limit for permanent uploads.
- [File Has Expired](https://signatureapi.com/docs/v1/errors/filed-expired) (`filed-expired`, HTTP 409): The upload you used has expired.
- [Upload Already Stored](https://signatureapi.com/docs/v1/errors/upload-already-stored) (`upload-already-stored`, HTTP 409): The upload has already been converted to a permanent file.
- [Upload Key Conflict](https://signatureapi.com/docs/v1/errors/upload-key-conflict) (`upload-key-conflict`, HTTP 409): The key specified in the request is already in use by another upload in your account.
- [Could Not Download File](https://signatureapi.com/docs/v1/errors/cannot-download-file) (`cannot-download-file`, HTTP 422): SignatureAPI could not download the file from the URL in your request.
- [Could Not Parse File](https://signatureapi.com/docs/v1/errors/cannot-parse-file) (`cannot-parse-file`, HTTP 422): SignatureAPI could not read the uploaded file as a PDF or DOCX.
- [Invalid File Format](https://signatureapi.com/docs/v1/errors/invalid-file-format) (`invalid-file-format`, HTTP 422): The server could not read the upload as a PDF or DOCX file.
