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

# Idempotency for safe retries

> Use the Idempotency-Key header to safely retry POST requests without creating duplicate trades, actions, or accounts when networks fail or time out.

Idempotency keys let you retry `POST` requests safely. If a request fails due to a network error or timeout, you can resend it with the same key and get the original response back — without creating a duplicate.

## How it works

Include an `Idempotency-Key` header with a unique value on `POST` requests:

```bash theme={null}
curl -X POST https://api.yoshi.ai/paper-trading/accounts/acc_123/trades \
  -H "Authorization: Bearer yoshi_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: buy-aapl-2026-04-10-001" \
  -d '{"symbol": "AAPL", "side": "buy", "quantity": 10}'
```

If you send the same request again with the same key:

| Scenario                       | Result                                             |
| ------------------------------ | -------------------------------------------------- |
| Same key, same parameters      | Returns the cached response (no duplicate created) |
| Same key, different parameters | Returns `409 Conflict`                             |

## Generate keys

Use UUIDv4 for unique keys, or derive them deterministically from your own identifiers:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { randomUUID } from "crypto";

  // Random key
  const key = randomUUID();

  // Deterministic key (same input always produces the same key)
  const key = `trade-${accountId}-${symbol}-${side}-${Date.now()}`;
  ```

  ```python Python theme={null}
  import uuid

  # Random key
  key = str(uuid.uuid4())

  # Deterministic key
  key = f"trade-{account_id}-{symbol}-{side}-{int(time.time())}"
  ```
</CodeGroup>

<Tip>
  Deterministic keys are useful when you want the same logical operation to always map to the same key — for example, "buy AAPL in portfolio X today" should only happen once regardless of how many times you retry.
</Tip>

## Which endpoints support idempotency

| Endpoint                                   | Supports `Idempotency-Key`                  |
| ------------------------------------------ | ------------------------------------------- |
| `POST /paper-trading/accounts`             | Yes                                         |
| `POST /paper-trading/accounts/{id}/trades` | Yes                                         |
| `POST /actions`                            | Yes                                         |
| All `GET` endpoints                        | Not needed (reads are naturally idempotent) |

## Key lifetime

Idempotency keys are cached for **24 hours**. After that, the same key creates a new resource. Design your keys so that reuse after 24 hours either doesn't happen or is intentional.

## Best practices

* **Always use idempotency keys** on `POST` endpoints in production. Network failures happen — make your retries safe by default.
* **Generate the key before the request**, not after. If the request succeeds but the response is lost, you need the same key to retrieve the result.
* **Don't reuse keys across different operations.** Each logical operation should have its own key.
* **Log your keys.** If something goes wrong, the idempotency key helps trace what happened.