HTTP status codes

Katana API uses standard HTTP status codes to indicate the success or failure of API requests. Katana will return an error with the corresponding status code if a request fails.

In general, there are three status code ranges one can expect:

  • 2xx success status codes confirm that a request worked as expected
  • 4xx error status codes indicate an error related to the information provided (e.g., a required parameter was omitted)
  • 5xx error status codes are uncommon and would indicate an error with our servers


4xx and 5xx responses may be returned for any request and clients should be ready to cater to them.

All errors return with this same structure:

  "error": {
    "statusCode": <STATUS_CODE>
    "name": <ERROR_NAME>,
    "code": <ERROR_CODE>,


HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

  "error": {
    "statusCode": 422,
    "name": "UnprocessableEntityError",
    "message": "The request body is invalid. See error object `details` property for more info.",
    "code": "VALIDATION_FAILED",
    "details": [
        "path": ".city",
        "code": "maxLength",
        "message": "should NOT be longer than 10 characters",
        "info": {
          "limit": 10

If you encounter an error, the response will contain an error object with the following attributes:

statusCodeA number indicating the HTTP error code.
nameName of the error.
messageHuman readable description of the error.
codeThe type of error returned.
detailsThe invalid fields and their associated errors. Only applies to validation errors.

Error codes and how to resolve them

Status CodeAction
Make sure your request is formatted correctly.
Make sure your API token is correctly entered.
Make sure the URI is formatted correctly.
Check the details property for a specific error message.
The rate limit has been reached. Please try again later.
The server encountered an error. If this persists, please contact support.