Skip to navigation
eSignature API 101Rules and resource limits

Handling API responses

View as Markdown

Responses are usually JSON or XML-formatted objects. In some cases, such as when requesting a document, the response is data.

Response status

Successful API responses are in the 200 range. The body of the response has the result.

StatusDescription
200Successful
201Created.
Example: An envelope has been successfully created.
204No Content response.
400Bad Request.
Example: The request is missing information or not legal XML or JSON.
401Unauthorized.
Example: Your integration key is incorrect.
403Forbidden.
Example: user lacks permission to complete this action.
408Request timeout.
415Unsupported media type.
Example: Your request may be in XML, but you did not specify Content-Type: application/xml in the request header.
429Too many requests.
444No response. Indicated dropped connection by server.

Error results have a response body that describes the error:

{
  "errorCode": "PARTNER_AUTHENTICATION_FAILED",
  "message": "The specified integrator key was not found or is disabled. An integrator key was not specified."
}

Response headers

In addition to the standard response headers, API responses include the following headers.

HeaderDescription
X-BurstLimit-LimitThe maximum number of API requests you can make in a 30-second burst.
X-BurstLimit-RemainingThe number of API requests left before you reach the burst limit.
X-RateLimit-LimitThe maximum number of API requests you can make.
X-RateLimit-RemainingThe number of API requests left before you reach the limit.
X-RateLimit-ResetThe time, in Unix Epoch terms, when the rate limit will be reset.
Content-TypeThe format of the response. Usually one of application/json, application/xml, or application/pdf.
Content-DispositionPresent only if the body is an attachment. Specifies the attachment’s file name.

Response body

API responses use the following conventions:

  • All response fields are in camelCase: userName, envelopeId.
  • All values that represent constants or enumerations, except for errors, are given in lowercase: status: 'created'.
  • Error constants are in uppercase.
  • Fields with uri in their name are relative to the base URL.
  • Fields with url in their name are fully qualified URLs.
  • All times are in UTC.

By default, responses are formatted as JSON. Otherwise, results are rendered according to the Content-Type header in the request. For example, if you request a document from an envelope, the response body contains the data of a PDF file, and the content type is application/pdf.