Exception handling

This page explains how payment senders can validate payments against their receiving partner's RPO schema, and generate "instructed" business exceptions.

The Test Harness generates instructed exceptions in "Sending Test" mode only (as mock receiver).

Instructed exceptions

There are three types of RippleNet exceptions:

Instructed: exceptions created by the member who controls the payment.
Asynchronous: exceptions created by other members who control the payment, as well as RippleNet internal exceptions.
Synchronous: RippleNet HTTP error in response to an API request.

RPO validation

Schema violations trigger a payment failure. Each schema violation is mapped to an error code defined in the errorMapFilename property; and each error code is added to the payments failure reasons.

Caution

Accepted payments are only processed by the mock receiver Test Harness if the user_info is in the form of a JSON object. If the user_info is an array (as allowed by the RippleNet API), the payment is ignored.

Triggering exceptions

Exceptions are generated in two ways:

If the inbound RPO doesn't align with the active RPO schema, the payment fails with a "RECEIVER_DATA_VALIDATION" failure type and an error code determined by the error mapping file.
If the inbound RPO contains the "instructed_failure" key, the payment fails with both the failure type and an error code determined by the error mapping file.

To trigger an instructed business exception, add a field called instructed_failure to the user_info during the Accept quote step. Set the value of this field to failure_type-failure_code (that is, type + hyphen + code), for example:

	{
		"instructed_failure": "RECEIVER_DATA_VALIDATION-AC01"
	}

Failure types and codes

The Test Harness supports all receiver failure types: RECEIVER_DATA_VALIDATION, RECEIVER_LOCK_FAILURE, and RECEIVER_PROCESSING_ERROR. The failure type determines the stage at which the payment is failed.

Sender return requests