On this page, you will find everything you need to know about errors within Yousign API

Error types

HTTP Status CodeCode
400 Bad RequestInvalid request.
401 UnauthorizedInvalid authentication, check that your are using the correct API Key on the right environment (Sandbox / Production).
403 ForbiddenAccess to this resource is forbidden in this context.
404 Not FoundThe requested ressource was not found.
429 Too Many RequestsToo many requests sent in a given amount of time. Please reduce the number of calls or rely on webhooks instead of polling. Learn more about rate-limiting.
500 Internal Server ErrorServers are not working as expected. The request is probably valid but needs to be requested again later.
503 Service UnavailableWe are currently under maintenance.

Understanding 4XX Errors

To help you troubleshoot your issues, all the 4XX errors contain additionnal information in the JSON response.

Key that identify the error type
Human readable message explaining the error
invalid_paramsOnly present for errors of type validation.error

Array of objects with attributes:

- name identifying the concerned field and

- reason describing the validation issue
    "type": "validation.error",
    "detail": "You have some invalid params in your payload.",
    "invalid_params": [
            "name": "delivery_mode",
            "reason": "Value must be in [\"none\", \"email\"]."
    "type": "document.unable_to_download_signature_request_not_in_done",
    "detail": "The signature request \"80c30a0e-84cd-4574-8161-8669f6603189\" is still ongoing, the completed documents are not available yet"

Errors we send back on any Client error (4xx HTTP requests).

Error codeDescription
audit_trail.not_ready_for_downloadThe audit trail is not ready to be downloaded yet
approver.already_attached_to_signature_requestAn approver with the same information is already attached to the Signature Request.
consumption.date_out_of_rangeThe given date range is out of the valid range.
contact.workspace_not_identicalA contact restricted to a single workspace cannot be used as a signer or approver for a signature request from another workspace.
date.out_of_rangeThe given date range is invalid: the start date is greater than the end date.
document.already_attached_to_a_signature_requestThe document is already attached to a Signature Request. To attach a document to another Signature Request you need to re-upload it first.
document.already_attached_to_an_electronic_sealThe document is already used for another electronic seal.
document.not_replaceableUnable to replace the document.
document.not_unlockableCannot upload the document because it fails to be unlocked.
document.not_usableThe document is not valid. For example its extension is invalid, or it's not readable.
document.size_too_largeSize of document is too large to be performed
electronic_seal_image.limit_reachedThe limit of images for the electronic seal has been reached.
electronic_seal.too_many_fieldsThe limit of fields for the electronic seal has been reached.
field.dimensions_not_validThe dimensions for the field are invalid.
field.only_one_of_type_signature_per_document_and_signerWith the current signature level, only one signature field per document and per signer is allowed.
field.type_not_allowed_for_documentThe field type is not allowed for the document. It might be because the document is already signed or the document doesn't support this kind of field.
otp.not_validThe given OTP (one-time password) is invalid.
otp.no_longer_usableThe given OTP (one-time password) cannot be used anymore.
otp.phone_number_not_compatibleThe phone number is not compatible with the current OTP mechanism.
otp.too_many_requestsToo many OTP requests done in the allowed time frame.
parameters_not_validYou have some invalid params in your payload.
resource.not_foundThis error corresponds to the 404 HTTP error for any resource.
signature_request.expiration_date_out_of_rangeThe given Signature Request's expiration date is not within the allowed range.
signature_request.delivery_mode_not_compatibleThe current action is not compatible with the current delivery mode.
signature_request.no_documentThe Signature Request doesn't have any document, therefore the actual action cannot be performed.
signature_request.not_activatableThe Signature Request is not activable in its current state.
signature_request.not_reactivableThe Signature Request can't be reactivated.
signature_request.metadata_already_existsThe Signature Request already has metadata. You can still update them.
signature_request.migratedThe signature request is migrated from an older version, it cannot be permanently deleted.
signature_request.sender_not_validThere is an error in the signature request's sender configuration.
signature_request.status_not_compatibleThe actual action is not compatible with the Signature Request's status.
signature_request.too_many_documentsThe number of documents in the Signature Request is greater than the authorized number.
signature_request.too_many_signersThe number of signers in the Signature Request is greater than the authorized number.
signer.already_attached_to_signature_requestA signer with the same information is already attached to the Signature Request.
signer.authentication_mode_not_allowed_for_signature_levelThe authentication mode and the signature level for the signer are not compatible.
signer.authentication_mode_not_compatibleThe Signer authentication mode is not compatible with the current action.
signer.authentication_mode_not_enabled_for_signature_levelThe signature level with the given authentication mode is not enabled for your organization.
signer.field_requiredThe Signer does not have any field. You need at least one field per Signer.
signer.otp_requiredThe Signer is associated to an authentication mode requiring an OTP (one-time password).
signer.phone_number_requiredSigner's phone number is required in this case.
signer.reordering_not_allowedReordering Signers is not allowed in this context.
signer.signature_level_not_availableThe given signature level for Signer is not available in the current context.
signer.signature_level_not_compatibleThe Signer signature level is not compatible with the current action
signer.signature_level_not_enabledThe signature level is not enabled for your organization.
signer.signature_level_not_identical_for_allAll Signers should have the same signature level for this specific Signature Request level.
signer.status_not_compatibleThe current action is not compatible with the Signer's status.
subscription.limit_reachedA limit has been reached concerning your current subscription.
subscription.status_not_compatibleThe subscription status is not compatible with the current action