Producing failures on purpose
For integration engineers who need to test how their client handles rejected and failed operations.
Use isolated sandbox resources to test refusal, asynchronous failure and recovery paths. Record the request, response and final resource state for each scenario without retaining credentials in the report. Run only scenarios agreed for your assigned environment; do not alter network or custody infrastructure to force a failure.
Test request refusals
The public transaction contract describes these reproducible input cases:
| Scenario | Expected contract result | Client assertion |
|---|---|---|
Send RELEASE or CANCEL with assetId, accountRef or amount | 400 | Correct the body; do not retry unchanged. |
Send LOCK with a caller-supplied params.lockId | 400 | The lock ID is assigned by the platform. |
Send a non-scalar value in transaction params | 400 | Validate the input before the next submission. |
| Complete an unknown lock ID | 404 | Reconcile whether the originating lock exists; do not create another intent blindly. |
| Reuse a customer/account registry key with a changed payload | 422 | Preserve the original intent/key mapping and report the conflict. |
Use POST /api/transactions and the endpoint's request schema for each body. Give each new test intent its own persisted idempotency key; reuse that key only when testing recovery of the same intent.
Test a failure after acceptance
An accepted response and a terminal failure are different assertions. Submit the test, retain its transaction ID and follow GET /api/transactions/{transactionId} until the result is known.
| Scenario | What to observe |
|---|---|
| A lock with an expiry in the past | The contract describes acceptance followed by FAILED with UNPROCESSABLE. |
| A burn or transfer above the settled available funds | The contract describes acceptance followed by settlement failure. Retain the actual failure/reason codes and break detail; do not infer them from an example message. |
| An approver rejects the task gating an operation | Follow the request outcome and transaction failure separately; use a named approver who is not the initiator. |
| A retry after the client loses the submit response | Replay the same key/body and assert that no second operation is created. |
Read Handle failures and GET /api/transactions/breaks for the resulting evidence. The public API has no general fault-injection endpoint for signing refusal, network outage, policy timeout or reconciliation breaks. Exercise such infrastructure scenarios with the operator or use contract-shaped mocks in your client tests; mocks verify client behavior, not live settlement.
Test webhook failures and recovery
Use an HTTPS receiver under your control and a dedicated test registration. Configure that receiver to return a deliberate 500, then call POST /api/webhooks/{id}/test. Inspect GET /api/webhook-events for attempts, failure class and retry state. Restore the receiver promptly after recording the result.
Also test duplicate delivery: accept the same signed event more than once and assert that your handler applies its business effect once. For a suspended registration, fix the receiver and update the registration to ACTIVE; then investigate and replay parked deliveries as described in Webhooks.
The documented delivery timeout is five seconds, and any 2xx acknowledges a delivery. Acknowledge after durable storage, then process asynchronously. A slower response can turn a correctly processed event into a duplicate delivery.
Record the outcome
For each test, retain the environment, API version, operation/resource IDs, idempotency key, HTTP status, observed state and reconciliation result. A missing event or local timeout is an unresolved outcome. Recover it through API reads and operator evidence before declaring failure or submitting a replacement instruction.
API Reference
Open an endpoint for request fields, response examples and the interactive API console.
Related pages
Updated 5 days ago