Rate Limits
RUN.world API calls are rate-limited per authenticated user (or per IP for unauthenticated traffic) to protect platform stability. When you exceed a limit, the server returns HTTP 429 Too Many Requests. Exact limits aren't published and may change; build for graceful degradation rather than a fixed throughput.
A few categories are stricter:
Text generation (
textGen.requestChatCompletionAsync) and image generation (imageGen.generate) are gated separately and may refuse at lower rates. Design these calls assuming they can fail, and keep your game playable when they do.Sensitive write operations (e.g. creating comments or accounts) have much tighter caps to prevent abuse.
Build for graceful degradation rather than aiming for exact throughput.
How errors arrive
Structured SDK failures are RundotApiError instances. Each one carries:
code
string
Machine-readable error code (e.g. RATE_LIMITED, UNKNOWN). Switch on this instead of parsing the message.
status
number
HTTP status when the error came over HTTP. 0 for transport/RPC errors that have no HTTP status.
detail
string | undefined
Optional human-readable cause from the server (e.g. an upstream provider's validation message).
Rate limits surface as RateLimitedError, a subclass of RundotApiError:
code
string
Always 'RATE_LIMITED'.
status
number
429, including when the original response crossed the host RPC bridge.
retryAfterMs
number
Server-suggested backoff in milliseconds. Read this to size your retry delay.
message
string
Defaults to Rate limited. Retry after Ns. when the server omits a custom message.
Handling 429
Detect a rate limit by checking the error code, then back off using retryAfterMs when it's present:
Best practices
On a
RATE_LIMITEDerror, back off before retrying.Read
RateLimitedError.retryAfterMs(milliseconds) off the caught error to size your backoff. The SDK consumes the HTTPRetry-Aftervalue internally; game code never needs to inspect raw headers or parseError.message.Do not retry tighter than once per second.
For text generation and image generation, build a non-AI fallback path. Don't gate gameplay on these calls succeeding.
Last updated