Exception handling

This page explains how payment senders can validate payments against their receiving partner's RPO schema, and generate "instructed" business exceptions per the RippleNet Rulebook. For more information, see Business Exception Handling in the RippleNet Rulebook.

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 (as required by the RippleNet Rulebook). 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:

Copy
Copied!
	{
		"instructed_failure": "RECEIVER_DATA_VALIDATION-AC01"
	}

Failure types and codes

For more information about failure types and error codes, see Returns and Failure Codes in the RippleNet RuleBook.

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

For returns processed by the receiver, the primary failure type is RECEIVER_PROCESSING_ERROR. With RippleNet Test Harness 1.6.0 and higher, you can use SENDER_RETURN for returns performed based on a request from the payment sender.