Idempotency for safe retries

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

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:

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

import uuid

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

# Deterministic key
key = f"trade-{account_id}-{symbol}-{side}-{int(time.time())}"

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.

Getting Started

Reference

SDKs

Concepts

Webhooks

Use Cases

Tools

Resources

Idempotency for safe retries

How it works

Generate keys

Which endpoints support idempotency

Key lifetime

Best practices

​How it works

​Generate keys

​Which endpoints support idempotency

​Key lifetime

​Best practices

How it works

Generate keys

Which endpoints support idempotency

Key lifetime

Best practices