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

# Idempotency and rate limits

> Reuse one logical mutation identity across safe retries and obey returned rate-limit timing.

Send `Idempotency-Key` on v1 POST, PUT, PATCH, and DELETE requests. Keys contain 16–200 letters, digits, `.`, `_`, `:`, or `-` and are scoped to the caller credential identity.

## Server behavior

* An identical request replays the original status/body and returns `idempotency-replayed: true`.
* Reusing a key with a different method, URL, content type, or body returns `idempotency_key_reused`.
* A concurrent duplicate returns `idempotency_request_in_progress` with `retry-after`.
* Records remain for 24 hours and response bodies are encrypted.
* HTTP 500 responses are not retained, allowing a safe retry decision.

```bash theme={"system"}
curl -X POST https://api.sndbox.app/v1/workflows/WORKFLOW_ID/runs \
  -H "Authorization: Bearer $SNDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: run-production-20260831-001" \
  -H "X-Sandbox-Request-Time: 2026-08-31T12:00:00.000Z" \
  --data '{"workspaceId":"...","deploymentId":"...","encryptedPayloadReference":"object://..."}'
```

## Client retries

The TypeScript client defaults to at most two retries and permits 0–5. It retries 429, 502, 503, and 504. A mutation is retried only when it has an idempotency key, and the same key and correlation ID are reused.

## Limits

The default API budget is 240 requests per IP per minute. Health checks allow 60; invitation acceptance and runner pairing are narrower. Responses expose `x-ratelimit-limit`, `x-ratelimit-remaining`, `x-ratelimit-reset`, and `retry-after` on 429.

Back off. Do not rotate identities to evade a limit.


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