Error status codes

Error Code	Meaning
400	Bad Request — check response for details and fix.
401	Unauthorized — Your API key is wrong.
403	Forbidden — API Key is not authorized to perform this action.
404	Not Found — The requested resource could not be found.
405	Method Not Allowed — Request URL invalid.
406	Not Acceptable — You requested a format that isn’t json.
410	Gone — The requested resource is no longer available.
422	Unprocessable Entity — validation failed; check error details and correct.
429	Too Many Requests — You’re making too many requests.
500	Internal Server Error — We had a problem with our server. Please contact support.
503	Service Unavailable — We’re temporarily offline for maintenance.

Exceptional errors

Exceptional errors indicate a problem with your request format.

Attribute	Type	Meaning
type	string	forbidden, not_found, routing_error, parameter_missing, unpermitted_parameters
message	string	Description of the error.
detail	object	Detailed information on the error, depending on the error.

rate_limit_exceeded

{
    "type": "rate_limit_exceeded",
    "message": "Throttle limit reached. Retry later."
}

not_found

{
    "type": "not_found",
    "message": "Resource not found: Couldn't find Order with 'id'=1762272",
    "detail": {
        "id": "1762272",
        "model": "Order",
        "primary_key": "id"
    }
}

parameter_missing

{
    "type": "parameter_missing",
    "message": "param is missing or the value is empty: order"
}

unpermitted_parameters

{
    "type": "unpermitted_parameters",
    "message": "found unpermitted parameter: :total",
    "detail": {
        "params": ["total"]
    }
}

Validation errors

Validation errors occur when a provided attribute does not meet the validation requirements on the model. The status code is always 422.

Example validation error

{
    "type": "validation_error",
    "message": "Email is invalid",
    "errors": {
        "attributes": [
            {
                "field": "email",
                "label": "Email",
                "name": null,
                "code": "invalid",
                "message": "is invalid"
            }
        ],
        "associations": {
            "tickets": {},
            "form_responses": {}
        }
    }
}

Example validation error with associations

{
  "type": "validation_error",
  "message": "",
  "errors": {
      "attributes": [],
      "associations": {
          "tickets": {
              "2148094": {
                  "type": "validation_error",
                  "message": "Name can't be blank",
                  "errors": {
                      "attributes": [
                          {
                              "attribute": "name",
                              "label": "Name",
                              "code": "blank",
                              "message": "can't be blank"
                          }
                      ],
                      "associations": {}
                  }
              }
          },
          "form_responses": {}
      }
  }
}

Error response

Attribute	Type	Meaning
type	string	always validation_error
message	string	All of the validation errors concatenated into a single message.
errors	object	Details on the individual validation errors. Look for the key relevant to the resource you are modifying.
errors[attributes]	array	Errors on the object itself.
errors[associations]	hash	Errors on associated objects.

Error node

Attribute	Type	Meaning
attribute	string	The attribute on the model that triggered the error.
label	string	A human readable version of the attribute name.
name	string	If the relevant attribute is a relationship, the name of that record.
code	string	The type of validation error. See below for possible codes.
message	string	A human readable version of the code.
detail	object	Any extra attributes that may be useful, depending on the error.

Association errors

When you are submitting nested parameters, e.g. tickets with an Order, the errors associated to those resources are specified in an array, in the errors attribute, with the key being the name of the association. E.g. for tickets submitted along with an order, the key to access those is errors.associations.tickets. Inside the association errors key, you will find a hash, indexed by the ID of the associated record.

Validation error codes

code	Meaning
blank	attribute is required
invalid	attribute format is invalid