Errors

HTTP Error Status Codes

We use the standard HTTP status codes found here. Any response with a status code of 400 or greater is considered an error.

Responses with a 4xx status code are due to errors caused by the client. The client should fix the error before trying to send the request again.

Responses with a 5xx status code are due to errors caused by our servers. For idempotent requests, the client can retry the request later, but should honor the Retry-After response header if one is provided. For non-idempotent requests it is recommended not to perform an automatic retry.

Validation errors

We use the status code 400 for errors in syntax, and the status code 422 for semantic request errors.

Examples of 400 errors:

• Missing a } in the JSON request body.
• Providing a string instead of a number in a request body.

Examples of 422 errors:

• Missing a required field in a request body.
• Providing a number that falls outside the valid range.

HTTP Error Response Body

All error response bodies have the following structure:

{ 
    "errors": { 
        "foo": [ 
            "must be an integer",
            "must be greater than 0" 
        ], 
        "bar": [
            "must be a valid ID",
        ]
    }
}

The errors property

The errors property is an object with various sub-properties corresponding to the error you are receiving.

Properties within errors

There will always be at least one property within errors. All properties are string arrays.

Typically, the property names will match the names of request body properties, query parameters, headers, or other request components for which an error has been identified.

The property name general is used for errors that don't correspond to a specific request component.