> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox error simulation

> 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.

<Warning>
  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.
</Warning>

## 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`)

Unrecognized codes return **400** with `error.code` `UNKNOWN_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`.

## Examples

### Timeout (availability / no timely response)

```bash theme={null}
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

```bash theme={null}
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"
    }
  }'
```

Alias (same effect in sandbox):

```json theme={null}
"metadata": { "error_code": "SANDBOX_SIMULATED_UNAVAILABLE" }
```

### Example 504 body

```json theme={null}
{
  "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](/en/api-reference/transactions/create)
* [Transaction monitoring overview](/en/use-cases/transaction-monitoring/overview)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.