Sandbox error simulation

​

Overview

​

How it works

1. Authenticate with an API key for a sandbox organization.
2. Call POST /transactions with either:
   • externalId starting with SIMULATE-ERROR-, or
   • metadata.sandboxErrorCode (canonical) or metadata.error_code (alias).
3. 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

1. metadata.sandboxErrorCode (if present and recognized)
2. metadata.error_code (if present and recognized)
3. Suffix after SIMULATE-ERROR- in externalId (for example SIMULATE-ERROR-TIMEOUT)

​

Catalog

​

Useful aliases

​

Examples

​

Timeout (availability / no timely response)

curl -X POST "https://api.gu1.ai/transactions" \
  -H "Authorization: Bearer YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "SIMULATE-ERROR-TIMEOUT",
    "type": "PAYMENT",
    "amount": 100,
    "currency": "USD"
  }'

​

Choose the error with metadata

curl -X POST "https://api.gu1.ai/transactions" \
  -H "Authorization: Bearer YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "txn-sandbox-any-id",
    "type": "PAYMENT",
    "amount": 100,
    "currency": "USD",
    "metadata": {
      "sandboxErrorCode": "SANDBOX_SIMULATED_UNAVAILABLE"
    }
  }'

"metadata": { "error_code": "SANDBOX_SIMULATED_UNAVAILABLE" }

​

Example 504 body

{
  "success": false,
  "error": {
    "code": "SANDBOX_SIMULATED_TIMEOUT",
    "message": "Sandbox simulated gateway timeout (controlled delay; the connection is not left hanging)"
  }
}

​

Scope

• Applies only to single POST /transactions. Batch create endpoints are not covered.
• Auth / permission failures (401 / 403 from middleware) are not simulated here — use an invalid key or role if you need those.
• Successful creates (201) are unchanged; this feature only simulates errors.

​

Related

• Create transaction
• Transaction monitoring overview