Handle OfflineCreator MCP rate limits and Retry-After

Stop the burst when OfflineCreator returns 429

An OfflineCreator MCP 429 is a rate-limit response, not a generation failure and not an authentication error. Stop issuing the same call immediately. Read the structured error details, preserve the `RATE_LIMITED` code, and schedule the next attempt no earlier than `retryAfterSeconds`. The API response also sends that delay in the HTTP `Retry-After` header.

Do not let every worker retry independently. Pause the shared queue for the affected key or user, keep one scheduler responsible for resumption, and leave already-created generation IDs alone. A retry should repeat only the request that received 429; it should not create a replacement for a generation that was already accepted.

Immediate action

Pause calls for the returned delayUse the server-provided delay instead of guessing a short sleep or continuously probing for recovery.

Do not change

Credentials, prompt, or modelA 429 reports request volume. Rotate credentials or edit generation input only when separate evidence points to another error.

Distinguish the 60-per-minute and 200-per-day budgets

The current OfflineCreator API defines 60 requests per minute and 200 generations per day. They are separate rolling limits with different identities. The request budget is counted per API key across authenticated `/api/v1` calls, so model listing, credit checks, status reads, uploads, cancellations, and generation starts can compete for the same 60-request window. Creating another worker does not create more capacity when every worker shares that key.

The daily generation budget is counted per user over a rolling 24-hour window. It applies to generation starts, not to every status read. Because it is user-scoped, splitting work across multiple keys for the same account does not create another daily allowance. The implementation calculates the retry delay from the oldest retained timestamp in the affected window, so the useful recovery time is the returned delay rather than midnight in the operator's local time.

Request window

60 requests per minute per API keyBudget every MCP-backed API call, including reads used by status polling.

Generation window

200 generation starts per rolling 24 hours per userA second key on the same account does not establish another user-level generation budget.

Budget polling before parallel generation work

The published OfflineCreator MCP package's `wait_generation` path polls generation status every 1.5 seconds by default. One continuously waiting job therefore uses about 40 status requests per minute before other tool calls are counted. Two simultaneous default wait loops can exceed a shared 60-request key budget even when only two generations were started. This is a client-source calculation, not a throughput guarantee: network delays and terminal completion can reduce the actual count.

For bounded automation, prefer fewer active wait loops, a longer polling interval in your own orchestrator, or explicit `get_generation` checks from one central scheduler. Spread checks across the minute instead of waking every job at the same instant. When a generation reaches `completed` or `failed`, remove it from the polling set immediately. If the MCP tool returns 429, suspend all status checks using that credential for the specified delay rather than letting each pending job probe separately.

Before a batch

Reserve request capacity for status and recovery callsGeneration starts are not the only consumers of the per-key minute window.

During a batch

Use one queue and stagger due timesCentral scheduling prevents synchronized pollers from turning one 429 into a retry storm.

After a terminal state

Stop polling that generationRepeated reads of completed or failed work consume request budget without changing the result.

Retry once, then return the job to the queue

Treat `Retry-After` as a minimum delay for the affected bucket. After it expires, release one due request, not the entire backlog. If that probe succeeds, continue at a controlled rate. If it receives another 429, accept the new server delay and return the work to the queue. Add a small random offset when many workers share a scheduler so they do not all resume on the same boundary.

Keep the original operation and its identifiers. Read-only calls such as `get_generation` can be retried after the delay. Before retrying a generation start, confirm that the earlier call did not return a generation ID or otherwise succeed before the client observed an error. A 429 response says the rejected request exceeded a limit; it does not establish that an earlier accepted request failed.

First release

One request after `Retry-After`A successful probe is evidence that the queue can resume gradually, not permission to flush every pending call.

Repeated 429

Use the newest delay and remain queuedBound attempts and surface the blocked state to a human instead of retrying forever.

Read the MCP error payload before choosing a delay

The current public stdio MCP client does not automatically retry a non-successful Studio API response. It parses the response body, raises a `StudioApiError` with the HTTP status and body, and the MCP server returns those fields in an error tool result. For a current API 429, inspect `details.retryAfterSeconds` and `details.limit`; do not rely on the model to infer a pause from prose alone.

If an MCP host hides structured tool details, capture the sanitized error result and timestamp. Do not log bearer credentials, cookies, prompts, source media, or unrelated environment values. A useful operational record contains the tool name, package and host versions, whether the call was a read or generation start, the 429 status, returned limit and delay, attempt number, and the number of workers sharing the credential.

Expected shape

status 429 with structured error detailsPreserve the status, `RATE_LIMITED` code, limit, and retry delay when the host exposes them.

Package behavior

Error is surfaced, not retried automaticallyThe surrounding workflow must own queueing, delay, attempt bounds, and human escalation.

Choose the next guide from the response code

Stay on this runbook only when the response is 429 with `RATE_LIMITED`. Return to the MCP troubleshooting directory when transport, OAuth, or scope evidence appears instead. Use the credits guide for 402 `INSUFFICIENT_CREDITS`. Use the stuck-generation guide only when a generation was accepted and remains nonterminal; status delay after acceptance is different from a request rejected by a rate limiter.

Editorial ownership boundary

This page owns OfflineCreator MCP and API 429 diagnosis, the 60-request per-key minute window, the 200-generation per-user rolling day window, and safe use of `Retry-After`. It does not own credit exhaustion, concurrent-generation conflicts, provider outages, authentication failures, or general MCP transport recovery. Revalidate the product limits monthly; consolidate this page into the MCP troubleshooting directory if the two current limits can no longer be verified.