Troubleshooting for common errors

Error message: This Account lacks sufficient permissions.

Description

The account does not have the permissions required for the request. The error message frequently includes a second sentence that specifies the feature for which the account does not have permissions.

This error reflects the permissions for the API account ID that was included in the API endpoint path. See Formatting API requests for additional information about request components.

This error can occur when creating envelopes using a feature not enabled in your account or in the account Admin settings. For example, the error message “Account lacks permission to send Envelopes over SMS” indicates that the Allow SMS delivery to recipients option in the Sending Settings might be disabled, as shown here:

Recommendations

Check whether your account has the correct Admin settings to create envelopes using the feature mentioned in the error message:

1. Log in to your Docusign account on the production or developer environment.
2. Select Admin from the top nav.
3. From the left nav, access the page that contains the setting relevant to the error message. For details about the available settings, see Major Sections of Docusign Account Administration.
4. If the setting is not enabled, enable it and save the change.

Note: If a setting does not appear as expected, it may mean that the feature is not enabled in your account plan. If you have a paid support plan or you are a Docusign Partner, contact Docusign Support for assistance. Other options are contacting your Docusign account executive or using the self-service resources listed in FAQ: Support for developers and Docusign APIs.

Error message: This account is not authorized to access the requested envelope.

Description

The authenticated user does not have access to the envelope referenced in a request.

The authenticated user is the user whose credentials were provided when generating the access token that was used to make the API call. See the topics below for details.

• Authorization Code Grant: Request the authorization code
• JWT Grant: Step 1. Request application consent
• Implicit Grant: Step 1. Obtain the access token

For example, this error can occur during an embedded signing workflow. Embedded signing recipients sign directly through your app’s UI instead of signing via an emailed link (known as remote signing). The basic workflow for embedded signing is:

1. An Envelopes:create call defines a recipient as an embedded signing recipient by including a clientUserId property.
2. An EnvelopeViews:createRecipient call returns a recipient signing URL. The clientUserId, userName, and email in this call must match the values in the Envelopes:create call.

Possible causes for this error during an embedded signing workflow include:

• An EnvelopeViews:createRecipient request was made for a recipient that did not have a clientUserId property defined in the Envelopes:create request.
• The authenticated user for the Envelopes:create request was different from the authenticated user for the EnvelopeViews:createRecipient request.

Recommendations

• Be sure to define your recipients correctly for embedded signing. You must specify a clientUserId property for a recipient in an Envelopes:create request (or in a later call to modify the envelope) to identify them as an embedded signing recipient. See How to request a signature through your app for a walkthrough and code samples.
• The clientUserId, email address, and user name must be identical in both requests. If they do not match exactly, you will not be able to generate an embedded signing view.
• For an embedded signing workflow, always authenticate as the same user for both the Envelopes:create and the EnvelopeViews:createRecipient requests. Do not authenticate as the envelope recipient for the EnvelopeViews:createRecipient request.
• See Docusign Developer FAQ - eSignature API for information about allowing both embedded and remote signing for a recipient.

Error message: An Error Occurred during anchor tag processing. Invalid document

Description

Docusign was unable to extract PDF text to find strings associated with anchor tags (auto-place tabs) in an Envelopes:create request. This can occur if a document is corrupt, password-protected, encrypted, or missing Unicode mapping for the embedded fonts.

Recommendations

• Check whether the PDF file is encrypted or password-protected, and if it is, remove the encryption and/or password protection.
• Flatten the document and resend the request with the new file. See How to resolve a document upload error by printing the document to a new PDF for steps to flatten a document.
• Use Adobe Preflight to check for text that cannot be mapped to Unicode, and address the mapping issues.
• Use fonts in the PDF file that can be reliably mapped to Unicode. These include Arial, Times New Roman, and Calibri.

Error message: The access token provided is expired, revoked or malformed.

Description

The access token in the request header is not valid for one of the following reasons:

• It expired. Access token expiration periods for the supported authentication methods are:

  • Authorization Code Grant: eight hours
  • JWT Grant: one hour
  • Implicit Grant: eight hoursWhen you make a request to obtain an access token, the expires_in field in the response contains the expiration period.

• A user or admin has revoked consent for the app to make calls on behalf of a user. See Obtain and revoke consent for more information.

• The access token does not have the correct format.

Recommendations

• Expired token: Follow one of these procedures to obtain a new access token:

  • How to get an access token with Confidential Authorization Code Grant
  • How to get an access token with JWT Grant
  • How to get an access token with Implicit Grant

• For Authorization Code Grant, you can also use a refresh token instead of a new access token, as described in Authorization Code Grant refresh tokens.

• Revoked token: You’ll need to grant consent again, either at the individual level or at the domain level. See Obtain and revoke consent for more information. You can also obtain a new token.

• Malformed token: Confirm that the access token was not inadvertently truncated and that it didn’t include extraneous leading or trailing characters. Also confirm that the request header consists of Bearer followed by a space and then the token.

• If you are using legacy authentication, Docusign recommends moving to a supported OAuth2 authentication workflow.

Error message: You’ve exceeded your burst API invocations. Your limit is ####. Please try again later.

Description

Your account exceeded the maximum number of calls allowed in a 30-second span from all apps associated with the account. The burst limit is 200 in the developer environment and 500 in the production environment. When an account reaches this limit, Docusign blocks all calls from the account until the start of the next 30-second span.

Recommendations

To avoid exceeding the limit and having calls blocked:

• Do not repeat calls within the same 30-second span.
• Monitor your application’s API usage by checking the X-BurstLimit-Limit headers included with most API responses. If your app is approaching the limit, delay nonessential calls until the next window starts.
• Rather than repeatedly polling to track envelope status, use Docusign Connect and a listener to subscribe to receive updates.
• Visit the API Usage Center to pinpoint causes of excess usage, and follow the recommendations you’ll find there to improve efficiency.
• See From the Trenches: API Rate Limits for additional background on limits and recommendations for reducing the number of calls your apps make.

Error message: The document specified was not found.

Description

A document ID specified in the request does not correspond to a document that the system can locate. Also generated when the account making the API call does not have permission to access the requested document.

Recommendations

• Make sure the documentID is correct.
• Make sure the document was not deleted or archived.
• Make sure that you’re using the right account from the right environment (demo or prod) and the correct envelope.
• Make sure that you’re using the correct account with access to this document.

Error message: Document upload not allowed. Envelope status changed during document upload.

Description

An attempt to upload a document to an envelope failed because the envelope changed status before the upload was completed.

Recommendations

• Lock the envelope while you’re uploading documents to it, then unlock it when you finish uploading the new document. Locking does not prevent adding documents, but it does prevent status changes.
• Make another attempt to upload the document.

Error message: The envelope is already locked.

Description

A request failed because the envelope is locked. This error can occur in response to an EnvelopeLocks:create request that references a locked envelope.

Recommendations

Before trying to lock an envelope, check whether the envelope is locked. See Common API Tasks: Locking and unlocking envelopes for details.

Error message: The envelope is not locked.

Description

A request failed because the envelope is not locked. This error can occur in response to an EnvelopeLocks:get, EnvelopeLocks:update, or EnvelopeLocks:delete request for an unlocked envelope.

Recommendations

• Before trying to retrieve, update, or delete envelope lock information, check whether the envelope is locked. See Common API Tasks: Locking and unlocking envelopes for details.
• Include code in your integration to catch and handle this error, since this response is expected for an unlocked envelope when you make one of the requests listed in the Description section.

Error message: Failed to acquire the lock because the envelope status was not ‘created’, ‘sent’ or ‘delivered’.

Description

Your integration attempted to lock an envelope with an EnvelopeLocks:create request, but the envelope was in a status that does not permit locking. Envelopes in these terminal statuses cannot be locked: complete, voided, and declined.

Recommendation

If this error is returned when a user attempts to modify an envelope, your integration should notify the user that the envelope status does not permit modification. If the envelope is not in a terminal status, the user may be able to try the update again later. Your integration can send an Envelopes:get request to check whether the status has transitioned to created, sent, or delivered, which would allow the modification to proceed.

See Envelope status code descriptions for more information about envelope statuses.

Error message: The user is not the owner of the lock. The envelope is locked by another user or in another application.

Description

Your integration attempted to modify an envelope, but the envelope has a lock in place. Docusign sets a lock on an envelope when a user opens it in a Correct session. Integrations can also set envelope locks programmatically. When an envelope has a lock, this error will occur when an app sends any request that attempts to modify the envelope without the appropriate lockToken in the X-Docusign-Edit header.

Recommendations

• Call EnvelopeLocks:get to return the lock expiration time. Your integration can wait for the expiration to retry the original request.
• If your integration sends an EnvelopeLocks:create request to lock an envelope, store the lockToken returned in the response. You must use the token in the X-Docusign-Edit header of subsequent requests if you need to modify a locked envelope. See EnvelopeLocks:create for details.
• See Common API Tasks: Locking and unlocking envelopes and From the Trenches: Who’s locking my envelopes? for more information about locks.

Error message: This account is out of credits. Ask your administrator to add more.

Description

This error reflects the envelope allowance for the API account ID that was included in the API endpoint path. See Formatting API requests for additional information about request components.

The cause of this error can vary depending on the environment:

Developer environment

Your account has exceeded the envelope send limits that Docusign enforces on the developer environment as part of our fraud prevention mechanisms.

Production

The limit in your production account is unrelated to the one in your developer account. In production, this error means that the number of envelopes sent exceeded the account plan maximum. For Docusign eSignature plans, every envelope sent in production counts toward the plan’s envelope allowance, whether or not the envelope was signed or completed. The number of envelopes sent for signature using PowerForms or bulk send also counts toward the allowance.

Recommendations

1. On production, access your account Plan and billing page.
2. Select View Usage Details to display the envelope allowance and current usage.
3. Depending on your account plan, you may be able to add envelopes to your allowance. See Add Envelopes and Seats for details.

If you have a paid support plan or you are enrolled in the Docusign Partner Program, you can also contact Docusign Support for assistance. Another option is to contact your Docusign account executive.

Error messages:

Only envelopes in the ‘Sent’ or ‘Delivered’ states may be corrected.

This account may not have ‘correct’ permission, or the envelope state is not ‘sent’ or ‘delivered’.

Description

This error commonly occurs in response to an EnvelopeViews:createCorrect request, which returns a URL that can be embedded in your application to enable a sender to correct an envelope. An EnvelopeViews:createCorrect request cannot be completed unless an envelope is in sent or delivered status. Envelopes in these terminal statuses cannot be corrected: complete, voided, and declined.

If this error is returned for an envelope that is in sent or delivered status, the ability to correct envelopes may not be enabled for the account.

Recommendations

If this error is returned when a user attempts to correct an envelope, your integration should notify the user that the envelope status does not permit correction. If the envelope is not in a terminal status, the user may be able to try the correction again later. Your integration can send an Envelopes:get request to check whether the status has transitioned to sent or delivered, which would allow the correction to proceed.

If this error is returned for an envelope in sent or delivered status, open a ticket with Docusign Support so that they can check the account permissions to see if Allow Envelope Correct is disabled.

See Envelope status code descriptions for more information about envelope statuses.

Error message: Only envelopes in the ‘Sent’ or ‘Delivered’ states may be voided.

Description

An API request was made to void an envelope that is not in Sent or Delivered state.

Recommendations

• Check the envelope status. It may already be voided, cannot be voided again.
• If the envelope is in any other state, you can delete it instead of voiding it.
• You may also purge a completed envelope if you want it to be completely removed from the system forever.

Error message: The envelope specified either does not exist or you have no rights to it.

Description

This error can occur because:

• The envelope ID in the request was not found in the environment to which you sent the request.
• The envelope ID in the request is for an envelope that has been deleted. In the developer environment, envelopes are automatically removed from the system after 30 days.
• The authenticated user that made the request is not the envelope sender or recipient, or is associated with a different account than the envelope sender.

The authenticated user is the user whose credentials were provided when generating the access token that was used to make the API call. See the topics below for details.

• Authorization Code Grant: Request the authorization code
• JWT Grant: Step 1. Request application consent
• Implicit Grant: Step 1. Obtain the access token

Recommendations

• Confirm that the envelope ID is valid for the environment to which you sent the request. For example, make sure that you are not referencing a production envelope ID in a call to the developer environment, or vice versa. To confirm where an envelope resides, log into the developer environment or production environment, select Agreements from the top navigation, and search for the envelope.

• If a user who is not the sender or recipient needs access to download envelope documents, include that user as a carbon copy recipient for the envelope.

• Use envelope sharing to provide access to other users in the account.

• Use JWT authentication with impersonation and do either of the following:

  • Impersonate the user that sent the envelope in order to perform the action. The user will have to consent once to an app using their credentials.
  • Send the envelope as the admin user that will perform subsequent actions on the envelope.

Error message: The specified envelope has duplicate recipients.

Description

An Envelopes:create or Envelopes:update request includes more than one recipient with the same recipientId value. This error can also occur if the same name and email appears more than once for a recipient in the same routing order.

Recommendation

Make sure that all recipientId values in the request are unique. If a recipient does legitimately need to sign under multiple roles in the envelope, they must have different routingOrder values.

Error message: Invalid envelope status. Cannot replace existing document as it contains tabs that would invalidate the digital signature of the new document.

Description

An attempt was made to update the envelope’s documents while the envelope is not in draft state. This error only occurs when you’re using Standards-based signatures functionality.

Recommendations

• If your integration has to modify documents in an envelope, make sure only to do that when in draft state.
• If the envelope was already sent, you can use the correct flow to enable modifications.
• You can void the existing envelope and send a new one with the updated documents instead.

Error message: Invalid envelope status. Envelope status is not one of: Created, Sent, Delivered, Correct.

Description

A request attempted to update an envelope’s components, such as recipients or documents, but the envelope was not in a status that allows this type of update. Permitted statuses for the type of update requested are created, sent, delivered, and correct. Envelopes in these terminal statuses cannot be modified: complete, voided, and declined.

Recommendation

If this error is returned when a user attempts to modify an envelope, your integration should notify the user that the envelope status does not permit modification. If the envelope is not in a terminal status, the user may be able to try the update again later. Your integration can send an Envelopes:get request to check whether the status has transitioned to created, sent, delivered, or correct, which would allow the modification to proceed.

See Envelope status code descriptions for more information about envelope statuses.

Error message: You’ve exceeded your hourly API invocations. Your limit is ####. Please try again later.

Description

Your account exceeded the maximum number of calls allowed in an hour from all apps associated with the account. The default hourly limit is 3,000. When an account reaches this limit, Docusign blocks all calls from the account until the start of the next hourly window.

Recommendations

To avoid exceeding the limit and having calls blocked:

• Do not repeat calls within the same one-hour window.
• Monitor your application’s API usage by checking the X-RateLimit-Limit headers included with most API responses. If you are approaching the limit, delay nonessential calls until the next window starts.
• Rather than repeatedly polling to track envelope status, use Docusign Connect and a listener to subscribe to receive updates.
• Visit the API Usage Center to pinpoint causes of excess usage, and follow the recommendations you’ll find there to improve efficiency.
• See From the Trenches: API Rate Limits for additional background on limits and recommendations for reducing the number of calls your apps make.
• Use the API limit management feature to increase the hourly limit for eSignature API calls.

Error message: Your account has reached the hourly limit of #### polling calls. To prevent this from happening again, enable webhooks to allow for real-time, automatic updates.

Description

Your app made too many GET requests for the same envelope in a one-hour window. See Service protection: New API errors for excessive polling and envelope updates for details.

Recommendations

• Rather than repeatedly polling to track envelope status, use Docusign Connect and a listener to subscribe to receive updates.
• Download multiple objects with a single API call when possible. For example, use the include query parameter for a call to the Envelopes:listStatusChanges endpoint instead of making additional API calls for subsidiary objects.
• Decrease the frequency of requests to check envelope status.
• Make sure that you don’t check status for envelopes that are already complete.

Error message: Invalid operation on captive recipient.

Description

A request to delete a saved signature for a recipient in an embedded signing workflow could not be completed. With embedded signing, recipients sign directly through your app’s UI instead of signing via an emailed link (known as remote signing). This error can occur if the Accounts:deleteCaptiveRecipient request body is improperly formed. This request requires an array of recipients.

Recommendations

Make sure that the recipient information in the request is properly formatted. See Accounts:deleteCaptiveRecipient for more information.

Error message: The email address for the recipient is invalid. The recipient Id follows.

Description

The email address for a recipient is missing, incomplete, or malformed. This error most commonly occurs in response to an Envelopes:create or Envelopes:update request.

Recommendations

Your integration should ensure that it supplies the correct email address for a recipient. To troubleshoot invalid emails, check the API request log to determine what was sent in the recipient’s email parameter. See From the Trenches: How to use API logs for details about retrieving request logs. See How to troubleshoot ‘invalid email’ errors for more information about email address issues.

Error message: A recipient ID is missing or invalid.

Description

An invalid string was used for a recipient ID in an envelope. A recipient ID must be either a number or a valid GUID; no other characters may be used in the recipient ID, and it must not be longer than 32 characters.

Recommendations

• If your recipient ID is a GUID, make sure that it’s a valid GUID format.
• You can use regular numbers for recipient IDs.
• Make sure your recipient ID is no longer than 32 characters.

Error message: The request contained at least one invalid parameter. Invalid value specified for envelopeId.

Description

The envelope ID in a request is not a valid GUID.

Recommendations

• Confirm that the envelope ID was not inadvertently truncated and that it doesn’t include extraneous leading or trailing characters.
• Confirm that the envelope ID is valid for the environment to which you sent the request. For example, make sure that you are not referencing a production envelope ID in a call to the developer environment, or vice versa. To confirm where an envelope resides, log into the developer environment or production environment, select Agreements from the top navigation, and search for the envelope.
• For more information, see From the Trenches: Troubleshooting INVALID_REQUEST_PARAMETER errors in the eSignature REST API.

Error message: The user name for the recipient is invalid. Envelope definition is missing a UserName for recipientId: [ID]

Description

An Envelopes:create request did not include a value for a recipient’s name property. The recipient name must be populated, even if the request also supplies values for the firstName and lastName properties.

Recommendation

Update the request to populate a value for the recipient name.

Error message: The user name for the recipient is invalid. ‘name’ not set for recipient with recipientId: [ID]

Description

When creating an envelope from a template, a name and an email address must be available for each recipient. The name and email address can either be hard-coded in the template’s role definition or supplied in the Envelopes:create request.

When creating an envelope from a template, errors can occur if Docusign cannot obtain a recipient’s name or email address from either the template definition or the Envelopes:create request. Errors will also occur for a mismatch between a recipient name and/or email address populated in both the template definition and in the Envelopes:create request.

This specific error code and message can be returned when:

• A recipient email address is populated in both the template definition and in the Envelopes:create request, but they do not match.
• A recipient name is omitted from both the template definition and the Envelopes:create request.
• A recipient role is set to be required on the template, but that recipient is not defined in the Envelopes:create request.

For information about template definition via the API, see How to create a template. For details about template definition in the UI, see Create Templates.

Recommendations

If you predefine a recipient name and/or email address in a template role definition, make sure that the Envelopes:create request omits those values from the corresponding recipient definition or supplies values that match the template.

If a template role definition does not include a name or email address, be sure to populate both the name and email for the recipient in the Envelopes:create request, or that role will be dropped if it is not set as required.

Error messages:

The document element did not contain the encoded document, or there is a problem with the encoding. No documents were found in the request.

The document element did not contain the encoded document, or there is a problem with the encoding. Bytes for document corresponding to documentId [ID] not found in request. ‘documentId=<x>’ possibly missing from Content-Disposition header.

Description

These errors can be returned in response to an Envelopes:create request when:

• The request is missing a documentBase64 property for an item in the documents array, or documentBase64 is set to an empty or invalid Base64 string.

• The request attaches documents to an envelope using multipart form data (binary transfer), and the multipart body has one or more of these issues:

  • It is missing the binary document content.
  • It is missing required components, such as Content-Type and Content-Disposition headers.
  • A documentId defined in the request’s documents array does not have corresponding binary file content with a matching ID in the multipart body.

Recommendations

• Make sure that the request includes a documentBase64 property set to a valid Base64 string for each document. See How to request a signature by email for code examples.

• If you are using multipart form data (binary transfer), confirm that the multipart body:

  • Is formatted correctly with the required headers and boundary delimiters
  • Includes the file content as binary data
  • Specifies document IDs in the Content-Disposition headers that match the IDs in the documents array.

See How to attach documents via binary transfer for code examples.

Error message: Freeform signing is not allowed for your account because it conflicts with other settings, please place signing tabs for each signer.

Description

Your integration is attempting to send an envelope that does not contain tabs for all signers and your account does not allow freeform signing (where recipients drag and drop tabs during signing). For example, CFR Part 11 accounts do not support freeform signing. This error can also be generated if document visibility is mandatory.

Recommendations

• Before sending the envelope, make sure that all signers have at least one tab assigned to them.
• If using a template, make sure that the recipientRoles are mapped correctly to the recipients of the templates.
• If you can use a different account that does not have this restriction, you may be able to send freeform signing envelopes.
• If you are using document visibility, change your account settings to not require document visibility for envelopes.

Error message: The Phone number has opted out of SMS. Phone number has opted out of SMS notifications. Recipient id: [ID]

Description

An Envelopes:create request specifies SMS delivery for a recipient, but the recipient has withdrawn their consent to receive SMS messages from Docusign.

Recommendations

To enable envelope delivery to a recipient after this error occurs, you can do either of the following:

• Direct the recipient to Docusign SMS and WhatsApp Service for instructions for them to provide consent to receive SMS messages.
• Update the deliveryMethod in the Envelopes:create request to Email, and provide an email address. See Using SMS and WhatsApp delivery with the eSignature REST API for more information.

To track recipients withdrawing consent for SMS messages, you can use a webhook listener to monitor the Docusign Connect events. See the SMS events section in the JSON SIM event reference for details about events related to opting in and out of SMS notifications.

Error message: The page image specified was not found.

Description

The system cannot locate or cannot render one of the images of one of the pages in the envelope. The image file referenced within the document or template might be missing, corrupted, or inaccessible to Docusign.

Recommendations

• Check all documents associated with the envelope throwing the error. Make sure to check the original document used and ensure that all of its pages are displayed correctly.
• If a document includes a reference to an embedded image, this reference may be missing, outdated, or inaccessible to Docusign and need to be fixed.
• Make sure none of the documents or images embedded in the documents require special permissions to access. They must all be publicly accessible on the internet for Docusign to render them.

Error message: The specified Integrator Key was not found or is disabled.

Description

You may see this error because:

• A call was made to the production environment after authenticating with an integration key that only exists on the developer environment.
• Your integration key has been disabled as a result of service protection issues.
• You used legacy header authentication and supplied an incorrect integration key. See Docusign Developer FAQ - eSignature API for details.

Recommendations

• For requests to a production environment, make sure that you have completed the Go-Live process for the integration key. You can check whether the integration key is in production by visiting the production Apps and Keys page.
• If you suspect that your integration key has been disabled, contact Docusign Support.
• See From the Trenches: Common authentication issues post Go-Live for additional scenarios that may result in the same error code with a different error message.
• If you are using legacy authentication, Docusign recommends moving to a supported OAuth2 authentication workflow.

Error message: The validation of the PDF file failed. (Document ID: [ID])

Description

Docusign was not able to read a Base64-encoded PDF document that your integration included in an envelope. This error can occur for the following reasons:

• The PDF file was corrupted.
• The file encoding mechanism did not generate a valid Base64 string.
• Docusign could not open the file because of password protection or file permissions.

Recommendations

• To check for corruption or encoding issues, use an application or online tool to convert the Base64-encoded string back to a PDF, and then try to open it.
• Make sure that the file does not have password or access restrictions.
• For additional PDF file troubleshooting recommendations, see Issues uploading documents: common errors, causes, and solutions.

Error message: A request plan item is not enabled for this account.

Description

The feature required for the request is not enabled for your account.

Recommendations

If you have a paid support plan or if you are enrolled in the Docusign Partner Program, contact Docusign Support for assistance. Other options are contacting your Docusign account executive or using the self-service resources listed in FAQ: Support for developers and Docusign APIs.

Error message: The token for an out of sequence recipient cannot be generated.

Description

This error can occur in response to an EnvelopeViews:createRecipient request, which returns a URL for an embedded signing session. This error means that the request attempted to generate a signing URL for a recipient whose assigned routing order does not match the current stage in the envelope’s signing workflow. The Envelopes:create request assigns a routingOrder property to each recipient. For example, if the current stage in the envelope’s signing workflow is 2, but the EnvelopeViews:createRecipient request references a recipient whose routingOrder property was set to 3, this error will occur.

Recommendations

Your integration should check which recipient’s routing order matches the current stage in the envelope’s signing workflow:

1. Use an EnvelopeRecipients:list request to return the routingOrder for each recipient and a currentRoutingOrder property that lists the current stage in the envelope’s signing workflow.
2. Generate the embedded signing URL for the recipient whose routingOrder matches currentRoutingOrder using EnvelopeViews:createRecipient.

Error message: The URL provided does not resolve to a resource.

Description

This error can occur for the following reasons:

• The endpoint URL in the request is not valid. For example, a GET request to /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/locks will cause this error because the correct endpoint URL is /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/lock
• A production request used the base URI https://docusign.net. This URL is incorrect. Production servers always have a subdomain: for example, https://na2.docusign.net. See Recommendations below for more information.
• The call is not an authentication request, but it was sent to one of the account servers: https://account-d.docusign.com (developer environment) or https://account.docusign.com (production). These servers are valid only for authentication requests.
• An Admin API request was sent to the eSignature REST base URI. See the Admin API Go-Live page for the correct Admin API developer environment and production URLs.

Recommendations

• Review the API Reference information for the request, and confirm that you are using the correct URL for the endpoint.

• Confirm that the base URI in the request is correct for the account by following these steps:

  1. After you obtain an access token, make a request to the UserInfo endpoint to obtain the base URI.
  2. Check the base_uri property in the response and be sure to parse the subdomain. For example, the base_uri might look like this: https://na2.docusign.net
  3. Your application should cache this base URI for use in all subsequent requests for the application’s entire session. The value typically doesn’t change unless a user is added to or removed from an account.

Error message: The signature provider name specified is not valid. Invalid signature provider name: [name]

Description

Your integration supplied an incorrect value for the signatureProviderName parameter when defining a digital signature provider for a template or envelope. This error is commonly received in response to a Templates:create, Envelopes:create, or EnvelopeRecipients:create request.

Recommendations

Your integration must include a valid value for signatureProviderName. See Standards-based signatures for a list of signature provider names.

Error message: The envelope cannot be sent to recipient. Signer has not given consent to receive SMS notifications. Recipient id: [ID]

Description

An Envelopes:create request specifies SMS delivery for a recipient, but the recipient has not provided consent to receive SMS messages from Docusign.

Recommendations

To enable envelope delivery to a recipient after this error occurs, you can do either of the following:

• Contact the recipient to obtain their consent to receive envelope notifications via SMS. See Opt-In Process for Senders for SMS and WhatsApp Delivery for details. See Sign Through an SMS Text Notification for a description of the signer experience for providing consent.
• Update the deliveryMethod in the Envelopes:create request to Email, and provide an email address. See Using SMS and WhatsApp delivery with the eSignature REST API for more information.

To track recipients providing consent for SMS messages, you can use a webhook listener to monitor the Docusign Connect events. See the SMS events section in the JSON SIM event reference for details about events related to opting in and out of SMS notifications.

Error message: Unable to load the document. The document needs to be repaired and that would invalidate existing digital signatures. Please repair the document, then get it signed and uploaded again

Description

Docusign will automatically attempt to repair documents that have certain types of minor errors. Sometimes, when using digital signatures, these repairs can invalidate the signature and therefore cannot be made.

Recommendations

• Create a new envelope with repaired documents for signature.
• If you cannot repair the documents yourself, upload the documents into an envelope and allow the system to fix them before sending the document out for signature.

Error message: The recipient you have identified is not a valid recipient of the specified envelope.

Description

This error can occur in response to an EnvelopeViews:createRecipient request, which returns a URL for an embedded signing session. This error means that the userName, email, or clientUserId supplied in the request does not match the value supplied in the Envelopes:create request that defined the envelope to be signed.

Recommendations

Your integration should ensure that the values of the userName, email, and clientUserId properties in the EnvelopeViews:createRecipient request match the name, email, and clientUserId values in the Envelopes:create request. See Deep dive into the embedded signing recipient view for additional information.

Error message: The given PDF contains content that is not allowed.

Description

A request that uploads documents includes one or more PDF files containing features that are not supported for your Docusign account. Unsupported features include PDF layers (optional content groups), which provide an alternative document view, and actions that can change the view when triggered by certain events. This error can also be triggered by hyperlinks in a PDF that Docusign identifies as potentially malicious.

Recommendations

• Remove PDF layers from the document.
• Remove any actions that are configured to execute when the PDF is opened.
• To explore options for updating your account plan to allow PDF layers and actions, contact your Docusign account executive.
• Remove URLs from the PDF that may have been identified as malicious.

Error message: One or both of Username and Password are invalid.

Description

Docusign was unable to authenticate the user making the request. This can occur for the following reasons:

• The base URI in an API request is not correct for the account.

• You are using legacy authentication instead of a supported OAuth2 authentication workflow, and one of the following is true:

  • The authenticated user has two-step verification enabled in their Docusign account.
  • The authenticated user’s domain requires single sign-on (SSO) login, and the user doesn’t have a login policy exception.
  • You have not obtained an exception for your integration to allow the continued use of legacy authentication (for REST apps) or non-app-password authentication (for SOAP apps). Docusign is deprecating these authentication flows. See OAuth 2.0 requirements and migration for information.

The authenticated user is the user whose credentials were provided when generating the access token that was used to make the API call. See the topics below for details.

• Authorization Code Grant: Request the authorization code
• JWT Grant: Step 1. Request application consent
• Implicit Grant: Step 1. Obtain the access token

Recommendations

• Confirm that the base URI in the request is correct for the account by following these steps:

  1. After you obtain an access token, make a request to the UserInfo endpoint to obtain the base URI.
  2. Check the base_uri property in the response and be sure to parse the subdomain. For example, the base_uri might look like this: https://na2.docusign.net
  3. Your application should cache this base URI for use in all subsequent requests for the application’s entire session. The value typically doesn’t change unless a user is added to or removed from an account.

• If you are using legacy authentication, Docusign recommends moving to a supported OAuth2 authentication workflow. If this is not feasible, see OAuth 2.0 requirements and migration for information about exception requests.

• If you are using legacy authentication and the authenticated user has two-step verification enabled, disable it by following the instructions in Disable Two-Step Verification.

• If you are using legacy authentication and SSO is required for the authenticated user, an organization admin can set a login policy exception. See How to exclude specific users from SSO requirements.

For additional information, see:

• From the Trenches: Who are you?
• Formatting API requests

Error message: One or both of Username and Password are invalid. Invalid access token

Description

The access token in an API request is either expired or not valid for the environment. Access token expiration periods for the supported authentication methods are:

• Authorization Code Grant: eight hours
• JWT Grant: one hour
• Implicit Grant: eight hours

Recommendations

• Follow one of these procedures to obtain a new access token:

  • How to get an access token with Confidential Authorization Code Grant
  • How to get an access token with JWT Grant
  • How to get an access token with Implicit Grant

• For Authorization Code Grant, you can also use a refresh token instead of a new access token, as described in Authorization Code Grant refresh tokens.

• If the token has not expired, confirm that you are sending API requests to the same environment where you obtained the token. Make sure that you are not using a token obtained from the developer environment in calls to production, and that you are sending calls to the correct production server for the account. Confirm that the base URI in the request is correct for the account by following these steps:

  1. After you obtain an access token, make a request to the UserInfo endpoint to obtain the base URI.
  2. Check the base_uri property in the response and be sure to parse the subdomain. For example, the base_uri might look like this: https://na2.docusign.net
  3. Your application should cache this base URI for use in all subsequent requests for the application’s entire session. The value typically doesn’t change unless a user is added to or removed from an account.

For additional information, see:

• From the Trenches: Who are you?
• Formatting API requests

Error message: The specified User is not a member of the specified Account.

Description

The authenticated user for the request is not a member of the account ID specified in the request.

The authenticated user is the user whose credentials were provided when generating the access token that was used to make the API call. See the topics below for details.

• Authorization Code Grant: Request the authorization code
• JWT Grant: Step 1. Request application consent
• Implicit Grant: Step 1. Obtain the access token

Recommendations

• Confirm that the authenticated user is a member of the account whose GUID appears in the request URL. You can do this via a request to the UserInfo endpoint after you obtain an access token.

• If you made the request under your account, you can also check the authenticated user’s account memberships in the Docusign web app:

  1. Check the production Apps and Keys page or the developer environment Apps and Keys page. Make sure that you log into the environment to which you submitted the call.
  2. Verify that the API Account ID listed here matches the accountId in the request.
  3. In the left navigation under Users and Groups, select Users.
  4. Verify that the authenticated user appears in the list of account users.

For more information, see:

• From the Trenches: Who are you?
• Formatting API requests
• Docusign Developer FAQ - General Administration and Authentication

Error message: The UserID did not identify a User in the system.

Description

The user properties in a request do not match any existing users.

Recommendations

• If you are filtering for users by an email address and user name in an Envelopes:listStatusChanges request, make sure that the both filter values match the same user. Check the list of production users or developer environment users.
• If you are filtering by user ID, make sure that you’ve supplied a valid GUID value and that it maps to an existing user on the environment.
• If you included multiple query parameters in a request, try eliminating them one by one until the request returns results. Then check the values in the response to see why none of them matched the parameters in your original request.
• Review the API Reference information for the request. For example, if you receive this error in response to an Envelopes:listStatusChanges request, check the parameter descriptions in the documentation to make sure that your request conforms to the guidelines.

Error message: The UserID does not have a valid membership in this Account.

Description

The base URI in an API request was not correct for the account. The UserID referenced in the error message is the authenticated user for the request.

The authenticated user is the user whose credentials were provided when generating the access token that was used to make the API call. See the topics below for details.

• Authorization Code Grant: Request the authorization code
• JWT Grant: Step 1. Request application consent
• Implicit Grant: Step 1. Obtain the access token

Recommendations

Confirm that the base URI in the request is correct for the account by following these steps:

1. After you obtain an access token, make a request to the UserInfo endpoint to obtain the base URI.
2. Check the base_uri property in the response and be sure to parse the subdomain. For example, the base_uri might look like this: https://na2.docusign.net
3. Your application should cache this base URI for use in all subsequent requests for the application’s entire session. The value typically doesn’t change unless a user is added to or removed from an account.

For additional information, see:

• From the Trenches: Who are you?
• Formatting API requests
• Why do I see Error: USER_LACKS_MEMBERSHIP

Error message: This User lacks sufficient permissions.

Description

The authenticated user for the request does not have the permissions required for the request. For example, a request to create an envelope from a template might cause this error if the user account doesn’t have permission to access templates.

The authenticated user is the user whose credentials were provided when generating the access token that was used to make the API call. See the topics below for details.

• Authorization Code Grant: Request the authorization code
• JWT Grant: Step 1. Request application consent
• Implicit Grant: Step 1. Obtain the access token

This error can also occur when trying to make certain types of updates to an envelope that’s already been sent. For example, this error can occur when you attempt to change the expiration of a sent envelope.

Recommendations

• Confirm the permissions in the permission profile associated with the authenticated user. It’s possible that the same user account exists in both the developer environment and production, but the user has different permissions in each environment. Check the production permission profile or the developer environment permission profile to confirm the user’s permissions.

• If the error occurs while trying to change properties of a sent envelope via an Envelopes:update request or other type of PUT request, set the properties before sending the envelope instead. One option is to set the properties during the Envelopes:create request. Another is to:

  1. Create the envelope as a draft (set the status to created instead of sent in the Envelopes:create request).
  2. Use an Envelopes:update or other type of PUT request to change the properties.
  3. Send an Envelopes:update request that changes the status to sent, which will send the envelope.

Error message: User is not an account administrator.

Description

The authenticated user for the request is not an administrator on the account, but admin access is required to perform the action. For example, a request to ConnectConfigurations:create requires admin access and will result in this error if the authenticated user is not an administrator.

The authenticated user is the user whose credentials were provided when generating the access token that was used to make the API call. See the topics below for details.

• Authorization Code Grant: Request the authorization code
• JWT Grant: Step 1. Request application consent
• Implicit Grant: Step 1. Obtain the access token

Recommendations

• Check the list of production users or developer environment users and confirm that the authenticated user is a member of the DS Admin permission profile or another profile with admin permissions. Make sure that you check the environment to which the call was submitted. A profile may appear to have admin permissions but may be missing specific permissions. See Administrator Permissions for details.
• If the user is not an admin, either modify the user and assign them to a permission profile with admin rights, or authenticate as a different user that has admin rights.
• If authenticating as a user with admin rights is not feasible, use JWT authentication, and have the integration impersonate an admin user.

Error message: This user is not the sender or a recipient of the envelope. Only the sender or a recipient of the envelope may perform the requested operation.

Description

The authenticated user for the request is not able to perform this action because only the sender or recipient is permitted to do so. For example, a request to Envelopes:listAuditEvents can return this error if the authenticated user is not the envelope sender or recipient.

The authenticated user is the user whose credentials were provided when generating the access token that was used to make the API call. See the topics below for details.

• Authorization Code Grant: Request the authorization code
• JWT Grant: Step 1. Request application consent
• Implicit Grant: Step 1. Obtain the access token

Recommendations

• If a user who is not the sender or recipient needs access to download envelope documents, include that user as a carbon copy recipient for the envelope.

• Use envelope sharing to provide access to other users in the account.

• Use JWT authentication with impersonation and do either of the following:

  • Impersonate the user that sent the envelope in order to perform the action. The user will have to consent once to an app using their credentials.
  • Send the envelope as the admin user that will perform subsequent actions on the envelope.

Error message: No User was found for given criteria.

Description

The user properties in a request did not match any existing users.

Recommendations

• If you are filtering for users by a complete email address in a Users:list request, try filtering by an email substring instead.
• If you supplied multiple query parameters in a request, try eliminating them one by one until the request returns results. Then check the values in the response to see why none of them matched the parameters in your original request.
• Review the API Reference information for the request. For example, if you receive this error in response to a Users:list request, check the parameter descriptions in the documentation to make sure that your request conforms to the guidelines.
• If you receive a JWT authentication error containing USER_NOT_FOUND, see Docusign Developer FAQ - General Administration and Authentication.