4. Error Handling Responses
The eSignatures API v3 uses HTTP error codes to give a rough idea of whether a call succeeded or failed, and a system of error codes in the response body to give more information incase things went wrong.
The used error codes for each call are listed in that call’s section. The meaning of each error code is further described in section 11.
The error responses are JSON containing the following list of objects:
Parameter | Content / Description | Type |
---|---|---|
Errors (array of objects) | List of the errors | Array |
ErrorCode | Error code with variable information | String |
Message | Error message detail text, not localized | String |
The error code field usually contains information for an external system. Such information is separated by a colon (‘:’) character. Everything before the colon character is of the form:
Group.Subgroup.Id
Everything after the colon character is variable and depends on the context of the error. If there are multiple values, then the first character will be a square opening bracket and the last character will be a square closing bracket.
Example response:
{
"Errors": [
{
"ErrorCode": "Request.RequiredFieldIsMissing:DocumentName",
"Message": "Required data field [DocumentName] is missing"
},
{
"ErrorCode": "Request.RequiredFieldIsMissing:DocumentLanguage",
"Message": "Required data field [DocumentLanguage] is missing"
},
{
"ErrorCode": "Document.InvalidTargetFileType:[Pdf,PdfA1A,PdfA2A]",
"Message": "Supported file types are [\"Pdf\",\"PdfA1A\",\"PdfA2A\"] but requested type was DocX"
}
]
}
Error codes can be reused: if the HTTP response code is HTTP 400 Bad Request, an error code like “Document.InvalidTargetFileType” indicates a value that is not supported by eSignatures. If the HTTP response code is HTTP 409 Conflict, an error code like “Document.InvalidTargetFileType” means that the request value can currently not be used because the configuration forbids it.
Note: any HTTP 500 Server Error or other 50x responses might deviate from the format described in this section as they are not part of the API.