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

# Simulação de erros no sandbox

> Simular falhas na criação de transações no sandbox — monitoramento transacional Gu1, com exemplos de timeout, 5xx e erros de validação.

## Visão geral

Somente no **sandbox**, `POST /transactions` pode devolver uma **resposta de erro predefinida** sem criar a transação. Use para testar como o seu sistema se comporta quando o monitoramento fica indisponível, dá timeout ou rejeita a solicitação.

<Warning>
  Esses gatilhos são ignorados em **produção**. Uma organização de produção sempre segue o fluxo normal de create, mesmo que você envie um `externalId` ou código de `metadata` de simulação.
</Warning>

## Como funciona

1. Autentique-se com uma API key de uma organização em **sandbox**.
2. Chame `POST /transactions` com:
   * `externalId` começando com `SIMULATE-ERROR-`, ou
   * `metadata.sandboxErrorCode` (canônico) ou `metadata.error_code` (alias).
3. A Gu1 responde com o HTTP status e o body correspondentes **de imediato** (ou após um delay limitado no timeout). **Nada é gravado** em `transactions`.

### Prioridade na escolha do código

1. `metadata.sandboxErrorCode` (se presente e reconhecido)
2. `metadata.error_code` (se presente e reconhecido)
3. Sufixo após `SIMULATE-ERROR-` no `externalId` (por exemplo `SIMULATE-ERROR-TIMEOUT`)

Códigos desconhecidos retornam **400** com `error.code` `UNKNOWN_SANDBOX_ERROR_CODE` e a lista de códigos válidos.

## Catálogo

| Código | HTTP | Notas |
| - | - | - |
| `TRANSACTION_VALIDATION_ERROR` | 400 | Mesmo formato plano da validação real |
| `INVALID_ENTITY_REFERENCES` | 400 | Refs de origem/destino não resolvidas |
| `INVALID_RISK_MATRIX` | 400 | `{ success: false, error }` |
| `ENTITY_ARCHIVED` | 403 | Entidade vinculada arquivada |
| `DUPLICATE_TRANSACTION_EXTERNAL_ID` | 409 | `externalId` duplicado |
| `CREATION_CONTRACT_QUOTA_EXCEEDED` | 429 | Cota excedida (simulada) |
| `ASYNC_RULES_QUEUE_UNAVAILABLE` | 503 | Fila indisponível (no sandbox não há insert) |
| `FAILED_TO_CREATE_TRANSACTION` | 500 | Shape legado: `{ error, details }` |
| `SANDBOX_SIMULATED_INTERNAL_ERROR` | 500 | `{ success: false, error: { code } }` |
| `SANDBOX_SIMULATED_UNAVAILABLE` | 503 | Serviço indisponível |
| `SANDBOX_SIMULATED_TIMEOUT` | 504 | Espera \~3s (máx. 5s) e responde — não deixa a conexão pendurada |

### Aliases úteis

Você pode usar aliases curtos no sufixo ou no metadata: `TIMEOUT`, `UNAVAILABLE`, `500`, `504`, `429`, `409`, `403`, `VALIDATION`, `DUPLICATE`, `QUOTA`, `INTERNAL_ERROR`, `FAILED_TO_CREATE`.

## Exemplos

### Timeout (indisponibilidade / sem resposta a tempo)

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

### Escolher o erro com 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 (mesmo efeito no sandbox):

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

### Exemplo 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)"
  }
}
```

## Escopo

* Aplica-se apenas ao **`POST /transactions`** individual. Endpoints de batch não estão cobertos.
* Falhas de auth / permissão (401 / 403 do middleware) não são simuladas aqui — use uma key ou role inválida se precisar.
* Creates com sucesso (201) não mudam; este recurso só simula **erros**.

## Relacionado

* [Criar transação](/pt/api-reference/transactions/create)
* [Overview de monitoramento de transações](/pt/use-cases/transaction-monitoring/overview)


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