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:
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}'
| 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:
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()}`;
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.
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.
