Simulação de erros no sandbox

​

Visão geral

​

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)

​

Catálogo

​

Aliases úteis

​

Exemplos

​

Timeout (indisponibilidade / sem resposta a tempo)

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

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

​

Exemplo de body 504

{
  "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
• Overview de monitoramento de transações