Error Responses

Wiki ▸ API Reference ▸ Introduction ▸ Error Responses

If an API request is successful, the API returns a 200 HTTP status code along with the requested data in the body of the response.

If an error occurs with a request, the API returns an HTTP status code and reason in the response based on the type of error. Additionally, the body of the response contains a detailed description of what caused the error. Here's an example of an error response:

{
  "error": {
    "code": 400,
    "message": "Invalid input",
    "developer_message": "",
    "request_id": "31acda7405784c4d8e8178c61885461a",
    "errors": [
      {
        "reason": "required",
        "location_type": "body",
        "message": "This field is required",
        "location": "attachments.0.shout.id"
      }
    ]
  }
}

The following table describes the elements can appear in the response body of error. Fields should be used together to help determine the problem. Also, the example values given below are meant for illustration and are not an exhaustive list of all possible values.

Element	Description
error	A container for the error information.
code	An HTTP status code value, without the textual description. Example values include: 400 Bad Request, 401 Unauthorized, and 404 Not Found.
message	Description of the error to be shown to the user.
developer_message	Description of the error for developer.
request_id	Reference for the developer.
errors	A container for the error details.
errors.location	The specific item within the location_type that caused the error. For example, if you specify an invalid value for a parameter, the location will be the name of the parameter.
errors.location_type	The location or part of the request that caused the error. Use with location to pinpoint the error. For example, if you specify an invalid value for a parameter, the location_type will be parameter and the location will be the name of the parameter. Example values include header, parameter and body.
errors.message	Description of the error.
errors.reason	Example values include invalid, invalid_parameter, required

Status Codes and Reasons

The following list shows the possible error codes, reasons, corresponding descriptions, and recommended action.

Code	Reason	Description	Recommended Action
400	required	The API request is missing required information. The required information could be a query parameter, header or body property.
400	invalid	The request failed because it contained an invalid information. The information could be the value of a query parameter, header or body property.
400	invalid_identifier	The request failed because it contained an invalid query parameter. Review the API documentation to determine which parameters are valid for your request.
400	invalid_header	The request failed because it contained an invalid header. Review the API documentation to determine which headers are valid for your request.
400	invalid_parameter	The request failed because it contained an invalid query parameter. Review the API documentation to determine which query parameters are valid for your request.
400	invalid_body	The request failed because it contained an invalid body property. Review the API documentation to determine which properties are valid for your request.
400	insecure_connection	The request failed because it was made using insecure connection i.e. HTTP instead of HTTPS.
400	bad_request	The API request is invalid or improperly formed. Consequently, the API server could not understand the request. In some cases where the API request requires external requests e.g. linking Facebook account, receiving errors from those external services will result in bad requests. Check developer_message for more details.
400	parse_error	The request failed because it contained improperly formed data i.e. submitting JSON objects while setting the content-type header to application/x-www-form-urlencoded.
401	auth_failed	The authorization credentials provided for the request are invalid. Check the value of the Authorization HTTP request header and the developer_message.
401	not_authenticated	The user must be logged in to make this API request. Check the value of theAuthorization HTTP request header.
403	permission_denied	The user has no permission to perform this action.
404	not_found	The resource associated with the request could not be found.
405	method_not_allowed	The HTTP method associated with the request is not allowed.
415	unsupported_media_type	The HTTP media type associated with the request is not supported.
429	throttled	Too many requests have been sent within a given time span.
500	internal_error	The API request failed due to an internal error.
503	backend_error	A backend error occurred.
503	connection_error	The request failed due to a connection error.
503	not_ready	The API server is not ready to accept requests.