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

# Simulación de errores en sandbox

> Simular fallas de creación de transacciones en sandbox — monitoreo transaccional Gu1, con ejemplos de timeout, 5xx y errores de validación.

## Resumen

Solo en **sandbox**, `POST /transactions` puede devolver una **respuesta de error predefinida** sin crear la transacción. Sirve para probar cómo se comporta tu sistema cuando el monitoreo no está disponible, hace timeout o rechaza el pedido.

<Warning>
  Estos disparadores se ignoran en **producción**. Una organización de producción siempre sigue el flujo normal de create, aunque envíes un `externalId` o código de `metadata` de simulación.
</Warning>

## Cómo funciona

1. Autenticáte con una API key de una organización en **sandbox**.
2. Llamá a `POST /transactions` con:
   * `externalId` que empiece con `SIMULATE-ERROR-`, o
   * `metadata.sandboxErrorCode` (canónico) o `metadata.error_code` (alias).
3. Gu1 responde con el HTTP status y el body correspondientes **de inmediato** (o tras un delay acotado en timeout). **No se escribe** ninguna fila en `transactions`.

### Prioridad al elegir el código

1. `metadata.sandboxErrorCode` (si está y es reconocido)
2. `metadata.error_code` (si está y es reconocido)
3. Sufijo después de `SIMULATE-ERROR-` en `externalId` (por ejemplo `SIMULATE-ERROR-TIMEOUT`)

Un código desconocido devuelve **400** con `error.code` `UNKNOWN_SANDBOX_ERROR_CODE` y el listado de códigos válidos.

## Catálogo

| Código | HTTP | Notas |
| - | - | - |
| `TRANSACTION_VALIDATION_ERROR` | 400 | Misma forma plana que la validación real |
| `INVALID_ENTITY_REFERENCES` | 400 | Refs de origen/destino sin resolver |
| `INVALID_RISK_MATRIX` | 400 | `{ success: false, error }` |
| `ENTITY_ARCHIVED` | 403 | Entidad vinculada archivada |
| `DUPLICATE_TRANSACTION_EXTERNAL_ID` | 409 | `externalId` duplicado |
| `CREATION_CONTRACT_QUOTA_EXCEEDED` | 429 | Cuota excedida (simulada) |
| `ASYNC_RULES_QUEUE_UNAVAILABLE` | 503 | Cola no disponible (en sandbox no se inserta fila) |
| `FAILED_TO_CREATE_TRANSACTION` | 500 | Shape legacy: `{ error, details }` |
| `SANDBOX_SIMULATED_INTERNAL_ERROR` | 500 | `{ success: false, error: { code } }` |
| `SANDBOX_SIMULATED_UNAVAILABLE` | 503 | Servicio no disponible |
| `SANDBOX_SIMULATED_TIMEOUT` | 504 | Espera \~3s (máx. 5s) y responde — no deja la conexión colgada |

### Alias útiles

Podés usar alias cortos en el sufijo o en metadata: `TIMEOUT`, `UNAVAILABLE`, `500`, `504`, `429`, `409`, `403`, `VALIDATION`, `DUPLICATE`, `QUOTA`, `INTERNAL_ERROR`, `FAILED_TO_CREATE`.

## Ejemplos

### Timeout (indisponibilidad / sin respuesta a tiempo)

```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"
  }'
```

### Elegir el error con 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 (mismo efecto en sandbox):

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

### Ejemplo de body 504

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

## Alcance

* Solo aplica a **`POST /transactions`** individual. Los endpoints de batch no están cubiertos.
* Fallos de auth / permisos (401 / 403 del middleware) no se simulan acá — usá una key o rol inválido si los necesitás.
* Los creates exitosos (201) no cambian; esta feature solo simula **errores**.

## Relacionado

* [Crear transacción](/es/api-reference/transactions/create)
* [Overview de monitoreo de transacciones](/es/use-cases/transaction-monitoring/overview)


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