API errors

When there is something wrong with a request, the API returns an error response that looks like this:

{
  "http_status_code": 422,
  "error_type": "validation_error",
  "error_code": "invalid_field",
  "error_message": "Invalid value for request field 'amount.quantity' - 0.00 is too low",
  "field": "amount.quantity"
}

http_status_code: the status code associated with the error
error_type: a general error category
error_code: a more specific error subcategory
error_message: [optional] a detailed description of the error
field: [optional] the field at fault, if applicable
errors: [optional] an array of individual errors, present when multiple fields fail validation at once

Error types

Errors are categorised into the following types:

validation_errors

Used for requests that are valid syntax-wise, but semantically-incorrect and cannot be processed by the server.
For example, if the request is missing required fields or header, or a request field is incompatible with a user's configuration.

{
  "http_status_code": 422,
  "error_type": "validation_error",
  "error_code": "missing_field",
  "error_message": "Request field 'amount' is missing",
  "field": "amount"
}

Multiple validation errors

When multiple fields fail validation at once, the errors may be returned together. The error_code is error_list and the individual errors are in the errors array, each with their own error_code, error_message, and field. The top-level error_message and field are not present as the details are in the array.

{
  "http_status_code": 422,
  "error_type": "validation_error",
  "error_code": "error_list",
  "errors": [
    {
      "error_code": "invalid_field",
      "error_message": "display_name contains invalid characters",
      "field": "display_name"
    },
    {
      "error_code": "invalid_field",
      "error_message": "Invalid id",
      "field": "payment_device_model_id"
    }
  ]
}

syntax_error

Used for syntactically-incorrect requests, i.e. where the grammar or form of the request itself is wrong.
For example, if the request is invalid JSON, or a query or path parameter is incorrectly-formatted.

{
  "http_status_code": 400,
  "error_type": "syntax_error",
  "error_code": "bad_request",
  "error_message": "invalid json request"
}

security_error

Used when there is an issue with authentication or permissions.
For example, if an API key has not been provided, or a user does not have sufficient permission to perform an action.

{
  "http_status_code": 401,
  "error_type": "security_error",
  "error_code": "missing_api_key",
  "error_message": "API key is missing"
}

internal_error

Used when the error is on Rootline's side.

{
  "http_status_code": 500,
  "error_type": "internal_error",
  "error_code": "internal_error",
  "error_message": "Something went wrong on our end"
}

idempotency_error

Used when there is an issue with the idempotency keys.

{
  "http_status_code": 422,
  "error_type": "idempotency_error",
  "error_code": "invalid_idempotency_key",
  "error_message": "Idempotency key is invalid"
}