Simulate create-transaction API failures in sandbox — Gu1 transaction monitoring, with examples for timeout, 5xx, and validation errors.
Overview
In sandbox only, POST /transactions can return a predefined error response without creating a transaction. Use this to test how your system behaves when monitoring is unavailable, times out, or rejects the request.
These triggers are ignored in production. A production organization always follows the normal create path, even if you send a simulation externalId or metadata code.
How it works
Authenticate with an API key for a sandbox organization.
Call POST /transactions with either:
externalId starting with SIMULATE-ERROR-, or
metadata.sandboxErrorCode (canonical) or metadata.error_code (alias).
Gu1 returns the matching HTTP status and body immediately (or after a short capped delay for timeout). Nothing is written to transactions.
Code selection priority
metadata.sandboxErrorCode (if present and recognized)
metadata.error_code (if present and recognized)
Suffix after SIMULATE-ERROR- in externalId (for example SIMULATE-ERROR-TIMEOUT)
Unrecognized codes return 400 with error.codeUNKNOWN_SANDBOX_ERROR_CODE and the list of valid codes.
Catalog
Code
HTTP
Notes
TRANSACTION_VALIDATION_ERROR
400
Same flat shape as real validation failures
INVALID_ENTITY_REFERENCES
400
Unresolved origin/destination refs
INVALID_RISK_MATRIX
400
{ success: false, error }
ENTITY_ARCHIVED
403
Linked entity archived
DUPLICATE_TRANSACTION_EXTERNAL_ID
409
Duplicate externalId
CREATION_CONTRACT_QUOTA_EXCEEDED
429
Quota exceeded (simulated)
ASYNC_RULES_QUEUE_UNAVAILABLE
503
Queue unavailable (no row is inserted in sandbox)
FAILED_TO_CREATE_TRANSACTION
500
Legacy shape: { error, details }
SANDBOX_SIMULATED_INTERNAL_ERROR
500
{ success: false, error: { code } }
SANDBOX_SIMULATED_UNAVAILABLE
503
Service unavailable
SANDBOX_SIMULATED_TIMEOUT
504
Waits ~3s (max 5s), then responds — connection is not left hanging
Useful aliases
You may use short aliases in the suffix or metadata: TIMEOUT, UNAVAILABLE, 500, 504, 429, 409, 403, VALIDATION, DUPLICATE, QUOTA, INTERNAL_ERROR, FAILED_TO_CREATE.