Skip to navigation
Platform 101Single-page applications and CORS

CORS error responses

View as Markdown
eSignature REST API 2.1 only

When a single-page application (SPA) API request to Docusign cannot be processed, Docusign returns a 403 Forbidden or 400 Bad Request error response. An error response is returned if any of the following is true:

  • App configuration issues

    • The domain where the script is hosted is not one of the allowed origins for the app.
    • The request did not use one of the allowed HTTP methods for the app.
    • The cors scope was not specified during authentication.
    • The request did not include an OAuth access token.
    • The request is not compatible with eSignature REST API v.2.1.
    • The API endpoint path did not include /accounts/{account_id}.

  • Account setting issue

    The authenticated user’s account does not have CORS enabled for the app.

    Your app’s error message for this issue should instruct the user to ask their account administrator to enable CORS for the app. This message is appropriate because the other possible error causes would occur during development, not in a production environment.

Additional error details

For some error conditions, the 403 Forbidden or 400 Bad Request response is accompanied by detailed error codes and messages. If available, these details appear in the Developer Tools for the browser in which the SPA is running. To see error details, follow these general steps for commonly used browsers, although the exact steps may vary depending on the browser:

  1. Launch the browser’s Developer Tools.
  2. Select the Network panel.
  3. In the list of API requests, select the request that received the error response.
  4. Display the Response tab to see the error code and message.

This is an example CORS error response displayed in Firefox.

CORS error message

General errors

This table lists CORS error codes and messages you may see in the browser’s Developer Tools when a 403 Forbidden response is returned, as well as troubleshooting guidance.

Error codeMessageTroubleshooting
Cors_Invalid_Api_VersionInvalid API Version: ensure the request URL contains the correct API version (e.g., >= v2.1) and try again.Make sure that the CORS request does not specify an eSignature REST API version earlier than v2.1. See Formatting API requests for more information.
Http_Method_Not_AllowedDisallowed HTTP Method: ensure the HTTP method being used is one of the supported methods (GET, POST, PUT, DELETE, HEAD) and try again.Check the allowed HTTP methods for the app and make sure that the method used in the request is enabled for the app.
Insecure_ConnectionInsecure Connection: ensure the CORS request is made securely (e.g., HTTPS) and try again.Make sure that the origin header in the CORS request specifies the https protocol. In the developer environment, http is allowed only if using localhost as the origin. All other origins must use https. In production, localhost is not permitted for origins, and https must always be used.
Invalid_Account_IdInvalid Account ID: ensure the request URL contains the correct account ID and try again.Make sure that the account ID in the CORS request is correct. The account ID appears under API Account ID on the Apps and Keys page.
Invalid_Origin_HeaderInvalid Origin Header: ensure the request is configured to use CORS and try again.Confirm that the value of the origin header in the CORS request is an absolute URI starting with http or https.
Misformatted_Account_IdInvalid Account ID: ensure the request URL contains the correct account ID and try again.Make sure that the CORS request is not missing the account ID, that the entire ID has been supplied, and that the ID does not contain invalid characters. The account ID appears under API Account ID on the Apps and Keys page.
Missing_Api_VersionInvalid API Version: ensure the request URL contains the correct API version (e.g., >= v2.1) and try again.Make sure that the CORS request includes the eSignature REST API version 2.1 or greater. See Formatting API requests for more information.
Missing_Config_Or_RequestThe request is missing or the account does not have the right permissions. Please check and try again.Make sure that CORS is enabled for the integration in the account-level CORS settings.
Missing_Cors_ScopeMissing CORS Scope: ensure the CORS scope parameter is included in the request and try again.The request failed because the cors scope was not specified during authentication. The SPA will need to re-authenticate and include the cors scope.
Origin_Not_AllowedDisallowed Origin Header: ensure the request is configured to use CORS and try again.Check the app’s CORS configuration and make sure that the request origin is included in the list of origin URLs.
Unsupported_Http_MethodUnsupported HTTP Method: ensure the HTTP method being used is one of the supported methods (GET, POST, PUT, DELETE, HEAD) and try again.Check the allowed HTTP methods for the app and make sure that the method used in the request is enabled for the app.

Public Authorization Code Grant errors

These errors can occur when an SPA authenticates using Public Authorization Code Grant. They will appear in the browser’s Developer Tools when a 400 Bad Request response is returned.

Error codeMessageTroubleshooting
invalid_grantcors_not_enabled_for_oauthMake sure that the Allow CORS for OAuth calls setting is enabled in the app’s CORS configuration.
invalid_grantcors_policy_not_setupCheck the app’s CORS configuration and make sure that the request origin is included in the list of origin URLs.
invalid_grantinvalid_originConfirm that the value of the origin header in the CORS request is an absolute URI starting with http or https.
Check the app’s CORS configuration and make sure that the request origin is included in the list of origin URLs.
invalid_grantorigin_required_but_not_includedConfirm that the CORS request includes a valid origin header.
invalid_grantunexpected_origin_includedReturned when non-public SPA clients (such as public native or confidential clients) use CORS and include an origin in the request header. Include an origin only for public SPAs using Public Authorization Code Grant.