> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.hellosign.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.hellosign.com/_mcp/server. # Warnings and Errors If an error or warning occurs, we'll return either an error or warning object in the JSON response. These can also be viewed in the API Reference documentation. ## Example Warning A response may contain one or more warnings. Check out the list of warning names below to learn more about the possible values of `warning_name` and their meaning. Here is an example of the JSON structure of the response: ```json { "warnings": [ { "warning_msg": "This SignatureRequest will be placed on hold until the user confirms their email address.", "warning_name": "unconfirmed" } ] } ``` ## Warning Names List and details of possible warnings that can be returned. | Warning | Description | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `unconfirmed` | The email address of the account making the Signature Request has not been confirmed. The Signature Request will be placed on hold until it is confirmed. | | `custom_field_value_too_long` | The value provided for a custom field is too long. The custom field will extend beyond the limits of its container and may not display the way you intended. | | `custom_field_values_too_long` | A summary of all values for custom fields that are too long | | `parameter_ignored` | One of the request parameters was ignored because it wasn't being used correctly | | `non_pdf_text_tags` | Text Tags were enabled for a file that is not a PDF, which may result in imprecise positioning. | | `form_fields_overlap` | Two or more of the form fields specified are overlapping, which may prevent signers from completing the document. | | `form_fields_placement` | Form fields must be placed within the document. | | `deprecated_parameter` | A parameter was provided which we no longer support. The value will be ignored. | | `parameter_conflict` | Two parameters have been provided which are in conflict. One parameter will be ignored. | | `parameter_missing` | An essential parameter was missing from the request and has been set to a default value. | | `partial_success` | The operation succeeded, but at least one non-essential part of the request failed. | | `test_mode_only` | A parameter was provided which will affect your app in test mode but will not affect it in production. Upgrade your account to use in production. | | `empty_value` | A non-essential parameter was provided but it does not have a value. The parameter will be ignored. | | `add_member` | A warning was generated while attempting to add a user to your team. | | `parameter_invalid` | A parameter was provided with an invalid value. The parameter will be modified or ignored. | | `oauth_grants_revoked` | OAuth user access grants have been revoked from this app due to a scope change. | | `cc_disabled` | The option to email a copy to the other signers and anyone CC'd is disabled for given account. | | `reassign_unsupported` | A template with signer reassignment was used on an endpoint that does not support it (e.g. bulk send with template). The template will still be used, but without signer reassignment enabled. | | `duplicate_template_ids` | Templates can only be used once in a signature request. A duplicated template ids was passed in the request. | | `value_too_precise` | The value for the parameter had a level of precision too high (e.g. `expires_at` have seconds level of granularity, instead of hour for time) | ## Example Error A response may only contain one error at most. Check out the list of error names below to learn more about the possible values of `error_name` and their meaning. Here is an example of the JSON structure of the response (or error POSTed to your callback url): ```json { "error": { "error_msg": "Unauthorized user.", "error_name": "unauthorized" } } ``` ## Error Names List and details of possible errors that can be returned. Each entry includes the HTTP status code, the likely cause, recommended remediation, and whether the request is safe to retry. `Retryable` values: * **No** — retrying the same request will not succeed; fix the request or state first. * **Yes** — the request can be retried as-is after waiting. * **Conditional** — retry only after resolving the underlying state (and with backoff). | Error | HTTP Code | Description | Cause | Remediation | Retryable | Backoff | | --------------------------------- | ------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------- | | `bad_request` | `400` | The request contained invalid or malformed parameters. | A parameter failed validation, or the request body was malformed. | Inspect `error_msg` and `error_path`, correct the offending parameter, and resend. | No | — | | `unauthorized` | `401` | The credentials supplied are missing or invalid. | Missing, malformed, or invalid API key or OAuth access token. | Verify the API key or OAuth token and the `Authorization` header, then retry. | No | — | | `payment_required` | `402` | The account must be credited or upgraded to perform this action. | The action requires a paid plan, additional quota, or API credits. | Upgrade the plan or add the required credits/quota, then retry. | No | — | | `forbidden` | `403` | The action is not allowed for these credentials or in the current context. | The authenticated account lacks access to the resource or operation. | Confirm the account has access to the resource and the required permissions. | No | — | | `not_found` | `404` | Nothing matches the requested resource. | The resource id does not exist or is not visible to this account. | Verify the id and that the resource belongs to the authenticated account. | No | — | | `method_not_supported` | `405` | The HTTP method is not supported for this endpoint. | The request used a verb the endpoint does not accept. | Use the HTTP method documented for the endpoint. | No | — | | `conflict` | `409` | The request was well-formed but conflicts with the current state. | The target resource is in a state incompatible with the request (e.g. a signature request is still being set up). | Wait briefly and retry, or listen for a callback event confirming the resource is ready. | Conditional | — | | `deleted` | `410` | The request was cancelled or deleted. | The resource has been cancelled or removed and is no longer available. | Do not retry; the resource is permanently gone. | No | — | | `unprocessable_entity` | `422` | The request was understood but the target entity cannot be processed. | The resource is still being processed, or it is in an error state. | If the resource is still processing, wait and retry; if it is in an error state, recreate/resend it instead of retrying. | Conditional | If still processing, retry with exponential backoff; if in an error state, do not retry. | | `exceeded_rate` | `429` | Your account's API request rate limit has been exceeded. | Too many requests were sent within the rate-limit window for this request type. | Pace requests using the `X-RateLimit-*` response headers and retry after the window resets. | Yes | Honor `X-Ratelimit-Reset` (Unix epoch); otherwise exponential backoff with jitter. No `Retry-After` header is sent. | | `max_faxes` | `429` | Too many fax transmissions are currently pending or transmitting. | The account has reached the limit of concurrent in-flight fax transmissions. | Wait for outstanding transmissions to complete, then retry. | Yes | Retry with exponential backoff once pending transmissions clear. | | `unavailable` | `503` | The service is temporarily unavailable. | A downstream dependency or the service itself is temporarily unavailable. | Retry later with exponential backoff. | Yes | Retry later with exponential backoff and jitter. | | `maintenance` | `503` | The request could not be completed because the site is under maintenance. | The API is in a scheduled maintenance window. | Retry once the maintenance window ends. | Yes | Retry later with exponential backoff. | | `invalid_recipient` | `400` | The recipient (fax number or email address) is invalid. | A recipient value did not pass validation. | Correct the recipient value and resend. | No | — | | `invalid_reminder` | `400` | The signature request reminder was invalid. | A reminder was attempted against an ineligible request (e.g. embedded, closed, or expired). | Only send reminders for eligible (non-embedded, open) signature requests. | No | — | | `team_invite_failed` | `403` | The team invitation could not be completed. | The invitee already belongs to a team, or the invite is otherwise not permitted. | Confirm the invitee is not already on a team before inviting. | No | — | | `signature_request_cancel_failed` | `400` | The signature request could not be cancelled. | The caller is not the requester, or the request is already fully executed/closed. | Only the requester can cancel, and only before the request is fully executed. | No | — | | `signature_request_remove_failed` | `400` | Access to the signature request could not be removed. | The signature request has not yet been fully executed, so access cannot be revoked. | Wait until all parties have signed, or call `/signature_request/cancel` to cancel incomplete requests instead. | No | — | | `signature_request_expired` | `400`, `403` | The signature request has expired. | The operation targets a request whose expiration has passed. Most endpoints return `400`; final-copy/download endpoints return `403`. | The request can no longer be acted upon; create a new signature request. | No | — | | `unknown` | `500` | An unexpected error occurred. | An unhandled server-side error, or a status code without a more specific `error_name`. | Retry transient failures; if it persists, [open a support ticket](https://www.dropbox.com/get_help/dropbox-sign-issue) with the request details. | Conditional | For transient 5xx, retry with exponential backoff; otherwise do not retry. | ## Asynchronous Error Events Some errors are not returned as an HTTP response. Instead they are delivered asynchronously to your callback URL as a webhook, where the error name arrives as `event.event_type`. Inspect `event.event_metadata.event_message` in the callback payload for details. See [Events and Callbacks](/docs/guides/events-and-callbacks/overview) for how to consume these. | Event (`event_type`) | Description | Cause | Remediation | Retryable | | --------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------- | | `signature_request_invalid` | Asynchronous error while processing a signature request. | A signature request could not be processed (e.g. invalid tags, fields, or merge data). | Inspect `event.event_metadata.event_message`, correct the request, and resend. | Conditional | | `template_error` | Asynchronous error while creating a template. | Template file processing failed (e.g. unsupported or corrupt file). | Recreate the template with a valid file; check status in the API dashboard. | Conditional | | `file_error` | Asynchronous error while processing an uploaded file. | A file attached to a request could not be processed. | Resend the request with a supported, non-corrupt file. | Conditional | | `sign_url_invalid` | An embedded signing URL has expired or become invalid. | The embedded `sign_url` is no longer valid (e.g. expired). | Generate a fresh embedded `sign_url` via the embedded sign URL endpoint. | Yes | | `unknown_error` | An unspecified asynchronous processing error occurred. | An unexpected error occurred while processing the request asynchronously. | Check the request status in the API dashboard; retry or contact support if it persists. | Conditional | ## Machine-readable error catalog For programmatic use (SDKs, AI agents, retry logic), this catalog is published as structured extensions in the OpenAPI specification, so you can branch on errors without scraping this page: * **`x-error-codes`** — a root map keyed by `error_name`, where each entry carries `http_status`, `summary`, `cause`, `remediation`, `retryable`, `backoff`, and `category`. Mirrors the **Error Names** table above. * **`x-error-events`** — the asynchronous webhook errors above, keyed by `event_type`, each with `delivery: webhook` (no `http_status`). * The `error_name` field on the `ErrorResponseError` schema is a closed `enum` of the canonical HTTP error names. Canonical spec: [openapi.yaml](https://raw.githubusercontent.com/hellosign/hellosign-openapi/main/openapi.yaml).