Spot APIs use standard HTTP status codes to indicate request outcomes:

• 2xx: Success
• 4xx: Client error
• 5xx: Server error

Failed requests typically include a short error code and an error_description with additional details. For example, a 401 error when exchanging a client ID and secret for a Bearer Token looks like:

{  
  "error": "access_denied",  
  "error_description": "Unauthorized"  
}

Other errors, such as the 429 error, may have a slightly different shape:

{
  "statusCode": 429,
  "message": "Too Many Requests"
}

Status Codes

Bad Request Codes

When responding with the HTTP 400 Bad Request status, Spot will include an object named spotErrors, which contains a list of errors. Each error will include an error code, a short description, and a detailed reason. For example, if a request was sent with several invalid values inside of the purchaser field, the response body might contain the following shape:

{
  "message": "Bad Request",
  "statusCode": 400,
  "spotErrors": [
    {
      "code": 2000,
      "description": "invalid string",
      "reason": "purchaser.firstName 2345 must be a non-empty string"
    },
    {
      "code": 2002,
      "description": "invalid ISO date format",
      "reason": "purchaser.dateOfBirth 07/13/2005 must be specified in YYYY-MM-DD format"
    },
    {
      "code": 2001,
      "description": "invalid email format",
      "reason": "purchaser.email foo@example must be a valid email address"
    }
  ]
}

The goal is to provide a set of unique error codes which are indicative of validation failures. The codes are static values, as published below. This allows a partner to interact with our API, and not have to perform string matching (and possibly further reasoning) in order to interpret why a request has failed.

The codes attempt to loosely follow a similar pattern to HTTP status codes (200-299 indicating success, 300-399 indicating redirection, etc.). Specifically, the Spot error ranges are 4 digit codes where:

• 1XXX is indicative of bad HTTP headers, shapes, or other business rules violations
• 2XXX is indicative of invalid formatting for fields within the request
• 9XXX is indicative of an error that Spot does not yet know how to interpret