Errors

Snapdocs Connect uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

Codes in the 2xx range indicates success.
Codes in the 4xx range indicates an error that failed given the information provided (e.g., a request is not authorized, a resource could not be found, etc.).
Codes in the 5xx range indicates an error with servers.

Below is the list of HTTP response codes that our API may return:

Http Response Code	Description
200	“OK” success code, for GET, PUT or HEAD request.
201	“Created” success code, for POST request.
204	No Content” success code, for DELETE request.
400	The request could not be understood, usually because the request body contains an error.
401	The OAuth token used has expired or is invalid.
403	The user is unauthorized to access the resource.
404	The requested resource could not be found. Check the URI for errors, and verify that there are no sharing issues.
409	The request is in conflict with the current state of the resource.
415	Content type is not supported. Currently, Content-Type header must be 'application/json'.
422	The request cannot be processed as submitted. Check your URL parameters.
429	Too Many Requests. The rate limit has been reached. Please try again later.
500	An error has occurred within the system.
503	The server is unavailable to handle the request. This should be very rare because Snapdocs APIs maintain three 9s uptime.

Snapdocs Connect provides additional information in the HTTP response body, including a JSON array of errors to help our clients. The error object has 3 fields:

Field	Type	Description
status	String	The conventional HTTP code associated with the error.
title	String	A high level description of the error.
detail	String	Further detail regarding the source of the error.

Below are examples of success and error responses.

2XX

2XX code indicates the success of the operation.

{
  "status": "201",
  "closing_uuid": "uuid of the closing",
  "snapdocs_url", "Snapdocs URL of the closing",
  "errors": []
}

4XX

Client errors indicate that Snapdocs found a problem with the client request, such as an authentication failure or missing required parameters. We suggest clients to log the response, fix the issue in the client application before submitting the request again.

401 Auth Error

401 errors may happen due to authentication or authorization problems. Clients should pay special attention to this error because it usually means invalid configuration or setup issues.

Example: error response from the Token API when clients send incorrect credentials.

{
  "error": "invalid_client",
  "error_description": "Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method."
}

Example: error response when clients send invalid access token to Closing API

{
  "errors": [
    {
      "status": "401",
      "title": "Invalid Authorization",
      "detail": "Authorization is invalid"
    }
  ]
}

Example: error response when clients don't have sufficient scope to access the requested resources:

{
  "errors": [
    {
      "status": "401",
      "title": "Invalid Authorization",
      "detail": "Insufficient scope"
    }
  ]
}

Other 4XX Client Errors

The 4xx status codes are often returned when a problem exists in the client application code. Client can find more information in the error object.

Example: error response when the closing does not exist:

{
  "errors": [
    {
      "status": "404",
      "title": "Not found",
      "detail": "Unable to find closing"
    }
  ]
}

Example: error response when required fields are missing in request:

{
  "errors": [
    {
      "status": "400",
      "title": "Missing Attribute",
      "detail": "signing_method must be present"
    },
    {
      "status": "400",
      "title": "Missing Attribute",
      "detail": "settlement_office_email must be present"
    },
   ]
}

Example: error response when clients send invalid data:

{
  "errors": [
    {
      "status": "422",
      "title": "Invalid Attribute",
      "detail": "settlement_office_email must be a valid email address"
    },
    {
      "status": "422",
      "title": "Invalid Attribute",
      "detail": "Closing user 2 email must be a valid email addres"
    },
    {
      "status": "422",
      "title": "Invalid Attribute",
      "detail": "Settlement agent 0 email must not be empty"
    }
  ]
}

429 Too Many Requests

Client applications encounter this error code when they have reached the rate limit. The simplest way to fix an HTTP 429 error is to respect the “Retry-after” header and wait to send another request.

{
 "error": "Throttle limit reached. Retry later." 
}

5XX Internal Error

When the Snapdocs systems fail to process the requests, clients will get 5XX error code. For example:

{
  "errors": [
    {
     "status": "500",
  	 "title": "Something Went Wrong",
  	"detail": "There was an error while processing your request"
   }
 ]
}

A common approach to handle 500 or 503 errors is to implement retry with exponential back-off method. If you continue to see this error, please contact the support at Snapdocs or your Customer Success Manager for assistance.