> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL. > > Documentation indexes by section: > - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt > - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt > - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt > - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt > > Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth > Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks > > OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json > MCP server: https://docusign.docs.buildwithfern.com/_mcp/server # Troubleshooting > Learn how to troubleshoot errors received in response to Web Forms API requests. > **Note** > > The Web Forms API is available in all developer accounts, but only in certain production account plans. Contact [Docusign Support](https://support.docusign.com/s/?language=en_US) or your account manager to find out whether the Web Forms API is available for your production account plan. This topic lists error codes and error messages that may be returned in response to Web Forms API requests or SDK method calls. If you are unable to resolve an issue with your application by following the troubleshooting recommendations, contact [Docusign Support](https://support.docusign.com/s/?language=en_US) for assistance. | HTTP status code | Error code | Error message | Description | | ---------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `400` | `BAD_REQUEST` | `[componentName] is a required field and must be filled by sender.` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because a required form field was not populated in the request. | | `400` | `BAD_REQUEST` | `Doc Exclusion Rule with document [documentName] must have parent field [parentField] filled by sender.` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the web form configuration included a conditional rule to include or omit a document, but the request did not supply the field value required to evaluate the rule. See [Additional prefill requirements for remote web form instances](/docs/web-forms-api/plan-integration/deliver-remote-instances-to-users#additional-prefill-requirements-for-remote-web-form-instances)`.` | | `400` | `BAD_REQUEST` | `Envelope Custom Field [componentName] must be filled by sender.` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the web form configuration included a required envelope custom field, but no value was provided. See [Additional prefill requirements for remote web form instances](/docs/web-forms-api/plan-integration/deliver-remote-instances-to-users#additional-prefill-requirements-for-remote-web-form-instances)`.` | | `400` | `BAD_REQUEST` | `’name' and 'email' for primary recipient must be provided in the request body.` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the primary recipient details were missing. The request body for a remote web form instance must include both a name and email for the primary recipient. See [Required user values for remote web form instances](/docs/web-forms-api/plan-integration/deliver-remote-instances-to-users#required-user-values-for-remote-web-form-instances)`.` | | `400` | `BAD_REQUEST` | `Recipients array must contain 'roleName', 'name', 'email' for each specified recipient.` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because one or more `recipient` objects in the `recipients` array did not include all required properties. Each `recipient` must specify a `roleName`, `name`, and `email`. See [Options to supply required user values](/docs/web-forms-api/plan-integration/deliver-remote-instances-to-users#options-to-supply-required-user-values)`.` | | `400` | `BAD_REQUEST` | `'recipients' should only be provided along with 'sendOption'.` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the `recipients` parameter can only be used with remote web form instances, which also require the `sendOption` parameter. See [Requirements to create remote web form instances](/docs/web-forms-api/plan-integration/deliver-remote-instances-to-users#requirements-to-create-remote-web-form-instances). | | `400` | `BAD_REQUEST` | `Send is not supported for a web form with attachment fields.` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because remote web form instances do not support attachment fields. See [Learn about remote web form instance delivery](/docs/web-forms-api/web-forms-101/when-to-use-embedded-or-remote-delivery#learn-about-remote-web-form-instance-delivery). | | `400` | `BAD_REQUEST` | `Unable to create instance because form is not activated.` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the web form configuration referenced in the request was not [activated](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=iri1669070601520.html). See [Web form configuration status](/docs/web-forms-api/plan-integration/retrieve-configuration-details#web-form-configuration-status) for more information. | | `400` | `INSTANCE_EXPIRED` | `Form instance [ID] expired at [datetime] UTC. Current time is [datetime] UTC.` | An [Instances:refreshToken](/docs/web-forms-api/reference/webforms/instances/refreshtoken) request or equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the web form instance referenced in the request expired, and no further instance tokens can be requested for it. If your application receives this error when attempting to refresh an instance token for a user, the application must create a new instance for the user. See [Web form instance expiration](/docs/web-forms-api/plan-integration/expirations-timeouts#web-form-instance-expiration) for more information. | | `400` | `INVALID_FORMAT_ACCOUNT_ID` | `accountId [ID] is not in a valid GUID format.` | The API account ID supplied in the endpoint URL is not a valid [GUID](http://guid.one/). Check your API account ID on the [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page. | | `400` | `INVALID_FORMAT_FORM_ID` | `formId [ID] is not in a valid GUID format.` | The web form configuration ID supplied in the endpoint URL is not a valid [GUID](http://guid.one/). See [Web form configuration ID](/docs/web-forms-api/plan-integration/retrieve-configuration-details#web-form-configuration-id) for steps to access a configuration and check the ID. | | `400` | `INVALID_FORMAT_INSTANCE_ID` | `instanceId [ID] is not in a valid GUID format.` | The web form instance ID supplied in the endpoint URL is not a valid [GUID](http://guid.one/). You can use an [Instances:listInstances](/docs/web-forms-api/reference/webforms/instances/listinstances) API request or equivalent [SDK](/docs/web-forms-api/sdks) method call to return a list of web form instances created from a web form configuration. | | `400` | `INVALID_STATE_PARAM` | `An invalid value was provided for the state query parameter. Valid values are [active, draft].` | A [Configurations:getForm](/docs/web-forms-api/reference/webforms/configurations/getform) request or equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the value of the `state` query parameter was not set to `active` or `draft`. See [Web form configuration status](/docs/web-forms-api/plan-integration/retrieve-configuration-details#web-form-configuration-status) for more information. | | `400` | `REQUIRED_FIELD_MISSING` | `Required field [fieldName] is missing.` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the request body did not include the required field listed in the error message. This error is returned in response to a [Configurations:getForm](/docs/web-forms-api/reference/webforms/configurations/getform) request or an equivalent SDK method call if the required `state` query parameter is not included. | | `400` | `VALIDATION_FAILED` | `clientUserId value max length is 100.` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the request body included a [clientUserId](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_clientuserid) value that was more than 100 characters long. See [Identify web form instance users](/docs/web-forms-api/plan-integration/identify-instance-users) for more information about `clientUserId`. | | `400` | `VALIDATION_FAILED` | `Email [emailInRecipientsArray] for roleName [roleName] in recipients array does not match with form value [emailInFormValues]` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the recipient email in the `recipients` object did not match the email in the `formValues` object for the specified `roleName`. See [Options to supply required user values](/docs/web-forms-api/plan-integration/deliver-remote-instances-to-users#options-to-supply-required-user-values). | | `400` | `VALIDATION_FAILED` | `Input of type 'CheckboxGroup' must be an array of string(s), containing elements from [value1,value2,value3].` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the request body [formValues](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_formvalues) object included a prefill value for a set of checkboxes that either was not an array of strings or included one or more values that were not among the allowed values. See [Obtain information about fields that can be prefilled](/docs/web-forms-api/plan-integration/prefill-instance-fields#obtain-information-about-fields-that-can-be-prefilled) for information about valid values. | | `400` | `VALIDATION_FAILED` | `Input of type 'Date' must be a valid date string. Expected date format: [yyyy-MM-dd].` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the request body [formValues](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_formvalues) object included a prefill value for a date field that was not in `yyyy-MM-dd` format. See [Supply prefill values in the request to create a web form instance](/docs/web-forms-api/plan-integration/prefill-instance-fields#supply-prefill-values-in-the-request-to-create-a-web-form-instance) for more information. | | `400` | `VALIDATION_FAILED` | `Input of type 'Email' must be a valid string.` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the request body [formValues](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_formvalues) object included a prefill value for an email field that was not a string. See [Supply prefill values in the request to create a web form instance](/docs/web-forms-api/plan-integration/prefill-instance-fields#supply-prefill-values-in-the-request-to-create-a-web-form-instance) for more information. | | `400` | `VALIDATION_FAILED` | `Input of type 'Number' must be a number and use a period as the decimal separator.` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the request body [formValues](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_formvalues) object included a prefill value for a number field that either was not a number or used a value other than a period as a decimal separator. See [Supply prefill values in the request to create a web form instance](/docs/web-forms-api/plan-integration/prefill-instance-fields#supply-prefill-values-in-the-request-to-create-a-web-form-instance) for more information. | | `400` | `VALIDATION_FAILED` | `Input of type 'RadioButtonGroup' must be a string and contain one of these options [value1,value2,value3].` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the request body [formValues](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_formvalues) object included a prefill value for a set of radio buttons that either was not a string or was not among the allowed values. See [Obtain information about fields that can be prefilled](/docs/web-forms-api/plan-integration/prefill-instance-fields#obtain-information-about-fields-that-can-be-prefilled) for information about valid values. | | `400` | `VALIDATION_FAILED` | `Input of type 'Select' must be a string and contain one of these options [value1,value2,value3].` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the request body [formValues](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_formvalues) object included a prefill value for a dropdown that either was not a string or was not among the allowed values. See [Obtain information about fields that can be prefilled](/docs/web-forms-api/plan-integration/prefill-instance-fields#obtain-information-about-fields-that-can-be-prefilled) for information about valid values. | | `400` | `VALIDATION_FAILED` | `Input of type 'TextBox' must be a valid string.` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the request body [formValues](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_formvalues) object included a prefill value for a text field that was not a string. See [Supply prefill values in the request to create a web form instance](/docs/web-forms-api/plan-integration/prefill-instance-fields#supply-prefill-values-in-the-request-to-create-a-web-form-instance) for more information. | | `400` | `VALIDATION_FAILED` | `Maximum allowed expirationOffset is 23976 hours (999 days).` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the request body included an [expirationOffset](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_expirationoffset) value that specified a web form instance expiration date more than 999 days in the future. This value is expressed in hours in the request, and the maximum allowed value is 23976. See [Web form instance expiration](/docs/web-forms-api/plan-integration/expirations-timeouts#web-form-instance-expiration) for more information. | | `400` | `VALIDATION_FAILED` | `Name [nameInRecipientsArray] for roleName [roleName] in recipients array does not match with form value [nameInFormValues]`. | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the recipient name in the `recipients` object did not match the name in the `formValues` object for the specified `roleName`. See [Options to supply required user values](/docs/web-forms-api/plan-integration/deliver-remote-instances-to-users#options-to-supply-required-user-values). | | `400` | `VALIDATION_FAILED` | `Phone country code [phoneCountryCodeInRecipientsArray] for roleName [roleName] in recipients array does not match with form value [phoneCountryCodeInFormValues].` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the recipient phone country code in the `recipients` object did not match the phone `countryCode` in the `formValues` object for the specified `roleName`. See [Options to supply required user values](/docs/web-forms-api/plan-integration/deliver-remote-instances-to-users#options-to-supply-required-user-values). | | `400` | `VALIDATION_FAILED` | `Phone national number [phoneNationalNumberInRecipientsArray] for roleName [roleName] in recipients array does not match with form value [phoneNationalNumberInFormValues]` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the recipient phone `nationalNumber` in the `recipients` object did not match the phone national number in the `formValues` object for the specified `roleName`. See [Options to supply required user values](/docs/web-forms-api/plan-integration/deliver-remote-instances-to-users#options-to-supply-required-user-values). | | `400` | `VALIDATION_FAILED` | `Provided sendOption value is [sendOption]. sendOption value must be 'now'.` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the `sendOption` value in the request body was invalid. The only supported value is `now`. | | `400` | `VALIDATION_FAILED` | `roleName [roleName] is invalid.` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because a `recipient` object included a `roleName` that did not exist in the web form configuration. You can obtain role names for a configuration from the `roleName` property in the [Configurations:getForm](/docs/web-forms-api/reference/webforms/configurations/getform) response's `recipientInfoMap` object. | | `400` | `VALIDATION_FAILED` | `These component names don't exist in the form: [component_name1, component_name2].` | An [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call failed because the request body [formValues](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_formvalues) object referenced one or more form field names that did not exist in the active version of the web form configuration. Use a [Configurations:getForm](/docs/web-forms-api/reference/webforms/configurations/getform) request or equivalent [SDK](/docs/web-forms-api/sdks) method call to get a list of valid form field names in the active configuration. If you use the [Web Forms builder](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=gpc1660591510274.html) to check the form fields in the configuration, the UI may reflect saved changes to the configuration that have not been [activated](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=iri1669070601520.html). Your application always uses the most recently activated version of the web form configuration. See [Obtain information about fields that can be prefilled](/docs/web-forms-api/plan-integration/prefill-instance-fields#obtain-information-about-fields-that-can-be-prefilled) and [Web form configuration version](/docs/web-forms-api/plan-integration/retrieve-configuration-details#web-form-configuration-version) for more information. | | `401` | `AUTHORIZATION_INSUFFICIENT_SCOPE` | `The access token is missing a required scope.` | The request failed because the access token supplied in the request header did not include a required scope for that request type. See [Required scopes](/docs/web-forms-api/plan-integration/authentication#required-scopes) for a list of the scopes needed for each request type. | | `401` | `AUTHORIZATION_INVALID_TOKEN` | `The access token provided is expired, revoked or malformed.` | The request failed because the access token supplied in the request header was not valid. See [AUTHORIZATION_INVALID_TOKEN](/docs/esign-rest-api/esign101/error-codes/troubleshooting-common-errors#authorization-invalid-token) for details and troubleshooting steps. | | `401` | `AUTHORIZATION_MISSING_TOKEN` | `The request does not include an access token.` | The request did not include an access token in the `Authorization` header. See [Authentication](/docs/web-forms-api/plan-integration/authentication) for more information. | | `401` | `USER_DOES_NOT_BELONG_TO_SPECIFIED_ACCOUNT` | `The specified user is not a member of the specified account.` | The authenticated user for the request is not a member of the account whose ID was specified in the request. See [USER_DOES_NOT_BELONG_TO_SPECIFIED_ACCOUNT](/docs/esign-rest-api/esign101/error-codes/troubleshooting-common-errors#user-does-not-belong-to-specified-account) for details and troubleshooting steps. | | `403` | `ACCOUNT_LACKS_WEBFORMS_PERMISSION` | `The Web Forms API is not included in your account plan or is not enabled for your account.` | The Web Forms API is available for all developer accounts. If this error occurs on the developer environment, contact [Docusign Support](https://support.docusign.com/s/?language=en_US) to request that the feature be enabled for your account. If this error occurs on production, it may mean that the feature is not included in your account plan or is not enabled. Contact Docusign Support or your account manager for assistance. | | `403` | `USER_LACKS_WEBFORMS_PERMISSION` | `The user does not have web forms permissions.` | The authenticated user for the request does not have permissions for the Web Forms feature. The authenticated user is the user whose credentials were provided when generating the access token that was used to make the API call. To provide Web Forms permissions, assign the user to the DS Admin permission profile or to a profile that has permissions specified in [Add Web Forms Permissions](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=kfl1679340366644.html). | | `404` | `RESOURCE_NOT_FOUND` | `Object with ID [ID] was not found.` | The ID specified in this error message may be a web form configuration ID or a web form instance ID supplied in an endpoint URL. For a web form configuration ID, this error indicates that no configuration with the specified ID exists, or the ID is for a configuration that does not belong to the account specified in the request. This error can occur in response to a [Configurations:getForm](/docs/web-forms-api/reference/webforms/configurations/getform) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call when the specified form ID exists but is not in the state (`active` or `draft`) listed in the request's `state` query parameter. If this error is received in response to an [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent SDK method call, it may mean that the web form configuration is not [activated](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=iri1669070601520.html). See [Web form configuration ID](/docs/web-forms-api/plan-integration/retrieve-configuration-details#web-form-configuration-id) for steps to access a configuration and check the ID. See [Web form configuration status](/docs/web-forms-api/plan-integration/retrieve-configuration-details#web-form-configuration-status) for more information about statuses. For a web form instance ID, this error indicates that the ID is for an instance that was not created from the web form configuration specified in the request, or that no instance with this ID exists. You can use an [Instances:listInstances](/docs/web-forms-api/reference/webforms/instances/listinstances) API request or equivalent SDK method call to return a list of web form instances created from a web form configuration. | | `500` | `INTERNAL_SERVER_ERROR` | `An internal server-side error has occurred.` | An internal error occurred on the Docusign platform. Retry the request. If the error persists, contact [Docusign Support](https://support.docusign.com/s/?language=en_US). | | `503` | `SERVICE_UNAVAILABLE` | `Service unavailable.` | An internal error occurred on the Docusign platform. Retry the request. If the error persists, contact [Docusign Support](https://support.docusign.com/s/?language=en_US). |