We follow standard conventions for using HTTP codes on all responses. For errors, where additional context can be provided, we may include this in the reponse body following a consistent model.

HTTP Codes

Here are some of the standard HTTP reponse codes we'll send back when something goes wrong:

CodeDescription
400Bad Request - something in the input wasn't right. We'll usually include more detail in the response body
401Unauthorised - check your API key
403Forbidden - you're trying to access something you don't have priveleges for
404Not Found - the resource you're operating on doesn't exist
429Too Many Requests - you're at your rate limit and should wait before retrying the operation
500Internal Server Error - Something went wrong at our end, this should only happen in rare cases

Error Model

For any error that contains additional detail and reasoning to the standard HTTP response codes), an array of errors will be returned.

This is particularly useful in cases where validation is performed and the API responds with a number of errors.

Example

For example, when creating an item with multiple required / validated fields, the response might look like:

HTTP Response Code: 400
Response Body:
{
  "errors": [
    {
      "title": "Missing 'name'",
      "detail": "The 'name' field is required and must be specified",
      "source": "Apigee"
    },
    {
      "title": "Invalid 'phoneNumber'",
      "detail": "The 'phoneNumber' field must be of type 'number'",
      "source": "Backend"
    }
  ]
}

Did this page help you?