Rate limits
Limits on the Typeship API, what a 429 looks like, and how the generated tooling handles it for you.
| Scope | Limit |
|---|---|
Anonymous generation (POST /api/v1/generate) | 20 requests per minute per IP address |
One-shot package downloads (GET /api/v1/generate/download) | 60 requests per minute per IP address; separate from generation |
| Authenticated endpoints | 300 requests per minute per API key or OAuth client/user credential |
| Hosted generations | Per plan. See Plans and limits. |
When a request checks its allowance, authenticated and anonymous responses include these headers, whether the request succeeds or fails:
| Header | Meaning |
|---|---|
RateLimit-Limit | Maximum requests in the evaluated window. |
RateLimit-Remaining | Requests left immediately after this request checked its allowance. Concurrent requests can consume them. |
RateLimit-Reset | Seconds until that window resets, measured when Typeship sends the response. 0 means the window has already ended. |
Use these values to pace requests. Requests across regions and instances count toward the same allowance. A long request can outlast its window; its remaining count describes the earlier window.
Idempotency replays do not consume the allowance and omit these headers. Requests rejected before checking the allowance also omit them, including invalid credentials, invalid idempotency keys, and requests waiting for an earlier keyed request to finish.
Over the limit, the API returns 429 with the code rate_limit_exceeded and a Retry-After header in seconds:
HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json
{ "errors": [{ "type": "rate_limit", "code": "rate_limit_exceeded", "message": "Too many requests. Retry after 42s.", "retryable": true, "suggested_action": "Wait for the Retry-After interval before retrying.", "docs_url": "https://typeship.dev/docs/typeship-api/errors#rate_limit_exceeded" }], "request_id": "req_..." }What the tooling does
The Typeship CLI, MCP server, and SDKs retry 429 automatically with backoff, honoring Retry-After, up to two retries by default. Generation wait helpers poll every three seconds by default, or at an interval you specify where supported. They do not delay requests based on the remaining allowance. If a request still fails, wait for Retry-After before trying again.
Repeated generation
Generation processes your whole spec, and large specs take seconds. If you generate in a loop, use a Project instead. Projects regenerate when the spec changes and not otherwise. See Generation behavior.