Error codes

Error codes

The Docusign REST APIs return either 200 (OK) or 201 (Created) when an API request successfully runs to completion. It may also return 204 (No Content) to that the requested action was completed successfully, but the server does not need to return any data or a new resource in the response body.

Status codes in the 400-500 range indicate failures. For APIs that process a single item, this overall status code determines success or failure. There are special considerations for PUT and POST calls that process multiple items. See Error response handling for API requests that support multiple items for more information on error response handling. If an API request is not successful, the HTTP response code returned is generally one of the following:

The following error codes occur with much less frequency:

In most cases, the response body contains a more detailed errorDetails structure when an error occurs. However, depending on the error, the server might return HTML in place of the errorDetails structure, or nothing in the case of certain error types.

General error response handling

The general flow for response handling is:

if (statusCode == 200 || statusCode == 201) {
  // successful call - but do special processing for multi-item PUT & POST requests
} else if (statusCode == 404) {
  // call was processed but the resource being accessed was not found
  // envelope doesn’t exist, user doesn’t exist, etc. There may not be any more details in the errorDetails response.
} else // other errors
{
  var errorDetails = Json.Decode(response.body);
  if (errorDetails != null) {
    // process errorDetails.errorCode - See table of error codes
    if (errorDetails.message != null) {
      // use errorDetails.message to get more information in textual form.
    }
  }
}

Error response handling for API requests that support multiple items

The eSignature REST API supports many calls that operate on multiple items, such as adding one or more users to an account or adding one or more documents to a draft envelope. This decreases the number of HTTP requests required to perform some common operations. For API requests that support multiple items, the overall HTTP response code will be 200 (OK) or 201 (Created) if the API request has run to completion, which means all items in the request structure were processed. This response code is returned even if there were failures for individual items in the array.

The response body contains information about each item processed, and the structure for each item contains an errorDetails element if that item was not successfully processed.

You are responsible for checking for the errorDetails element for each item in the array to perform proper error handling. The general response processing logic for these types of APIs is:

if (statusCode == 200 || statusCode == 201) {
  // check for errors with each item processed.
  var itemsArray = Json.Decode(response.body);
  foreach(var item in itemsArray) {
    if (item.errorDetails != null) {
      // an error occurred during processing - handle it
      string errorCode = item.errorDetails.errorCode;
      string errorMessage = item.errorDetails.message;
      // perform error handling based on errorCode
    } else {
      // item processing was successful
    }
  }
} else {
  // statusCode indicated overall error with the request.
}

Next steps

• See Troubleshooting for common errors for causes and resolutions for specific errors.
• Learn more about Envelope status codes.
• Get an overview of Recipient status codes.