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

# Rate Limits and Retry Contracts

> Find the limit for the service you call, interpret throttling, and preserve safe replay behavior.

StateSet services do not share one rate-limit plan or one set of response headers. Use the
contract for the exact service, endpoint, and deployment you call. Local embedded-engine calls
do not consume a hosted HTTP request quota.

## Find the authoritative limit

| Interface | Where to look | What to verify |
| - | - | - |
| ResponseCX | The endpoint page’s **Access** section | Required scope and requests per minute from the checked-in API specification |
| Commerce HTTP | Your provisioned deployment and endpoint contract | Availability, configured limits, batch size, and replay support |
| Voice, Sync, EDI, NSR, Temporal, Sandbox, Computer Use | The service’s reference and deployment configuration | Quota scope, supported headers, and whether throttling is tenant-, key-, or endpoint-specific |
| Embedded commerce | [Local quickstart](/stateset-icommerce/stateset-icommerce-quickstart) | Local runtime capacity and concurrency; no hosted HTTP quota |

For example, [ResponseCX agent creation](/api-reference/responsecx/agents-create) declares
**30 requests per minute** in this repository’s contract. That is an endpoint-specific value,
not a platform-wide allowance. Read the relevant reference again when changing services.

The earlier generic Starter/Growth/Scale tables and universal batch-size claims have been
removed: they did not identify a service contract. If your endpoint does not publish a limit,
obtain it from your deployment administrator or [support](/support) before sizing production
traffic. An omitted limit does not mean unlimited access.

## Inspect the actual response

With a ResponseCX key scoped for agent reads, inspect status and headers without mutating data:

```bash theme={null}
curl --silent --show-error --fail-with-body \
  --dump-header response-headers.txt \
  --output response-body.json \
  --header "Authorization: Bearer ${RESPONSECX_API_KEY:?Set your ResponseCX API key}" \
  'https://response.stateset.com/api/v1/agents'
```

A successful request returns HTTP `200` and an agent list. On failure, keep the status,
redacted body, and request ID if present. Do not print or share your authorization header.

A service may emit `Retry-After` on a `429`. It can contain a delay in seconds or an HTTP date.
Follow that delay if present; otherwise use bounded backoff. Do not assume every response
contains `X-RateLimit-*` or `RateLimit-*` headers, or interpret an undocumented reset field’s units.

## Decide whether to retry

| Result | Next action |
| - | - |
| `429` on a read | Wait according to the response; retry within an attempt and wait budget |
| `429`, timeout, or `5xx` on a write | Check endpoint replay support and reconcile uncertain outcomes before retrying |
| `401` or `403` | Fix credentials or scope; backoff will not repair access |
| `400` or validation `422` | Correct the request using field errors |
| Idempotency conflict | Preserve the original body for a retry, or use a new key for an intentionally new operation |
| Repeated throttling | Reduce concurrency and coordinate callers sharing the same quota |

<Warning>
  Automatic retries of writes require an explicit endpoint contract. Reuse the original
  idempotency key and payload when supported; a new key can create another operation.
  See [error handling](/guides/error-handling-best-practices) for uncertain outcomes.
</Warning>

## Batch size and capacity

Read each batch endpoint’s request schema for item limits. A limit on one operation does not
apply to another. Test a representative workload on an authorized test deployment and record
throughput, latency, `429` frequency, and the scope shared by concurrent clients.

Bound both pending work and in-flight requests. After throttling, pausing a queue does not
re-enqueue its failed item: retry logic must explicitly make another attempt. Avoid scaling
workers simply to overcome a quota shared by the same tenant.

## Continue

* [Tested read retry helper](/guides/api-rate-limiting) — bounded attempts and `Retry-After` handling.
* [API directory](/api-reference/introduction) — select the host and credentials.
* [Errors across engines](/api-reference/errors-across-engines) — interpret the correct error body.
* [Integration test plan](/guides/comprehensive-testing-guide) — verify outcomes and capacity.


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