Errors

Riverty uses conventional HTTP response codes to indicate the success or failure of an API request.

Everytime an API call is made, an HTTP status code is returned. Some API calls also return JSON response bodies that include information about the resource. Below is the definition of the HTTP response codes that are returned for every API call.

In general: Codes in the 2xx range indicate success.

Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.).

Codes in the 5xx range indicate an error with our servers (these are rare).

All errors conveyed by our APIs are represented as problem+json (RFC7807) messages. RFC7807 can be represented in both JSON and XML. Our APIs use JSON.

Error categories

In error responses returned from our APIs, you will always find a field category that indicates the type of error that occurred. There are two categories:

• BusinessError
• TechnicalError

These categories bears differing semantic meaning and are to be handled separately.

Technical errors

In the scenario of a TechnicalError occurring, it is safe to presume that request itself is valid - but could not be processed at this time. This is usually an intermittent error due to internal hick-ups like a failing network connection or overloaded application server.

When dealing with these errors you are free to retry / resend the same request without modification. If possible, we recommend queuing the resending with an increasing back-off period.

Business errors

In the case of a BusinessError appearing, it means that something is wrong with your request. This could entail a validation error of the request body, or that your request is in violation with a business rule. In any case, the response will always contain an error type indicating precisely what went wrong and how to rectify it.

When handling a business error, you cannot retry / re-send the same request without modification.

Error types

In error responses from our APIs, you will also always find a field type that defines what kind of error just happened.

Possible error types are documented within each endpoint in the API reference.

Example

Any error returned from our API will thus minimally look like the following:

Generic errors

In addition to the domain-specific error types documented under the API reference, we provide a set of cross-cutting, generic error types that your integration should be able to recognize and handle when encountered in any endpoint.

Validation errors

When validation of a request fails we will return you a validation error. A validation error indicates that there is something wrong with the format of your request. It could be that you are missing a field, not following the formatting of a field or trying to use invalid values.

Validation errors generally requires manual intervention, and can not be programmatically handled. In cases where you capture information from an end-user, you should strive to convey the failure reason from the error response back to your end-user - enabling them to rectify the failing input.

Validation errors always returns a category of BusinessError and type of https://developer.horizonafs.io/errors/validation-error.

The body of the validation error contains an invalid-parameters list that provides you with a name of the failing field/property and the reason it did not validate.

Example

Not found

If you are requesting an HTTP resource that does not exist, you will be returned an HTTP 404 Not Found response. These responses, like all errors in our APIs, adhere to the above-mentioned problem+json based format.

These errors always return a category of BusinessError and type of https://developer.horizonafs.io/errors/resource-not-found.

Example

Forbidden

If your integration does not possess sufficient authorization or permissions to perform the request you are attempting, you will encounter an error of forbidden.

These also comply with the problem+json format.

These errors always return a category of BusinessError and type of https://developer.horizonafs.io/errors/forbidden.

Example

Authentication required

If you attempt to access a resource without being properly authenticated, the API will ask you to authenticate by returning an error of unauthorized. See this page for more information on how to authenticate with the API.

These errors always return a category of BusinessError and type of https://developer.horizonafs.io/errors/unauthorized.