Our endpoints return standard HTTP status codes to indicate the success or failure of a request. In the event of an error, the response body will contain a JSON object with type, message, and help keys. For example:

{
  "type": "example",
  "message": "This is an example error",
  "help": "This is how you can fix it"
}

You can use the type key to programmatically handle different error scenarios. The message and help keys offer human readable descriptions of the error and may vary depending on the specific error.

Error types

The following is a list of error types that may be returned by our API. The message and help fields are examples and may vary depending on the specific error.

Type	Message (example)	Help (example)
`unauthorized`	Missing or invalid 'X-Api-Key' header.	Generate a key on https://app.runa.io/api-keys and pass using the 'X-Api-Key' header.
`forbidden`	You don't have permission to access the requested resource	Please check the path you are trying to access is correct and you have permission to access it. Also ensure you are using the correct API key in the 'X-Api-Key' header.
`bad_request`	There is a problem with your request payload or JSON format.	Please ensure your payload is being passed or check issues with a JSON validator.
`invalid_api_key`	Missing or invalid 'X-Api-Key' header	Generate a key on https://app.runa.io/api-keys and pass using the 'X-Api-Key' header.
`not_found`	The requested resource does not exist	The request path is likely incorrect, please check and try again.
`internal_server_error`	An internal server error occurred	Please try again, or contact [email protected] for assistance.
`validation_error`	There was an issue with the request payload	Please check your request matches the structure outlined in our API documentation: https://developer.runa.io/reference
`pagination_error`	There was an issue with the pagination parameters	Please check the pagination parameters are valid and try again.
`idempotency_validation_error`	Request payload does not match previous payload for this idempotency key.	Please use a new idempotency key if this is a new request, or check your payload has not changed if you're retrying a request.
`idempotency_in_progress`	We are already processing an order for this idempotency key	Please wait until this order has finished processing before resending this request.
`insufficient_funds`	Insufficient funds in {currency} balance to create order.	Please add more funds to your {currency} balance and try again.
`product_validation_error`	Not allowed to order products: <detail>	None
`currency_mismatch`	The currency requested in the payment_method, '<currency>', does not match the currency of the selected products, '<currency>'.	When the payment_method type is 'ACCOUNT_BALANCE', the currency specified must be the same as the currency of all of the products in the order.
`payment_method_unavailable`	The requested payment method is not available.	None
~~`invalid_card_id`~~ (deprecated)	Invalid card id.	The card id provided is invalid. Please verify the card id in your Runa account and try again.
~~`currency_not_supported`~~ (deprecated)	The currency of the requested products, '<currency>', is not supported for card payments.	When the payment_method type is 'CARD', the currency specified must be one of the following: ...
`invalid_execution_mode`	Invalid execution mode.	None
`ordering_restricted`	You cannot complete this order as you have reached your spending limit	We will send you an email with instructions with what to do next so you can continue to order as soon as possible. Please contact [email protected] if you do not get this.
`insecure_protocol`	HTTPS required	For security the Runa API only supports requests over HTTPS. Please try again with an HTTPS URL.