Skip to main content

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: a detailed description of the error
  • field: [optional] the field at fault, if applicable

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"
}

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"
}