Docs / Start

Limits

This page explains rate limits and async task admission limits tenants may hit during integration. Clients should back off or queue retries based on the returned error code.

API rate limits

GlobalRouter applies multiple layers of protection before business processing starts, so one caller, key, model, or abnormal source cannot destabilize tenant traffic. Exact thresholds depend on tenant plans, key configuration, and platform policy; public docs do not expose internal system configuration fields.

Limit	Response	Recommended handling
The current API key exceeds its configured request rate.	Returns `429` and `ROUTER_RATE_LIMITED`.	Reduce concurrency, add exponential backoff, and split business keys if needed.
The current tenant's total request rate is too high.	Returns `429`; other keys in the same tenant may also be affected.	Add tenant-side throttling and avoid submitting large batches at once.
Abnormally frequent requests from a source IP trigger protection.	Returns `429`.	Check retry loops, proxy egress, and task concurrency.
Protective throttling for the current model is triggered.	Returns `429` for that model dimension only.	Switch to an alternative model or reduce concurrency for that model.

When GlobalRouter rate limits a request, primary APIs return the standard error envelope.

{
  "error": {
    "code": "ROUTER_RATE_LIMITED",
    "message": "API key gr_xxx exceeded allowed requests per minute.",
    "type": "rate_limit_error",
    "request_id": "req_xxx"
  }
}

Provider-side protective limits can also apply. When an upstream limit is hit, the API returns 429, PROVIDER_RATE_LIMIT_EXCEEDED, and includes a Retry-After header when available.

Image and video task admission

Image and video tasks are controlled by tenant submit rate and in-progress limits for each resource. Provider + model control groups can add submit-rate and in-progress limits. A model group may contain multiple models; an unset limit does not apply.

Limit	Response	Recommended handling
The tenant image or video submit rate exceeds its limit.	The create API returns `429` and `TENANT_TASK_SUBMIT_QPS_EXCEEDED`.	Reduce submit rate and back off according to `Retry-After`.
The tenant image or video in-progress count exceeds its limit.	The create API returns `429` and `TENANT_TASK_IN_PROGRESS_EXCEEDED`.	Wait for tasks to complete before submitting more.
A Provider + model group submit rate exceeds its limit.	Synchronous requests return `429`; async tasks stay queued and retry later.	Reduce submission concurrency for that model group and avoid duplicate task creation.
A Provider + model group in-progress count exceeds its limit.	New work is rejected or retried before provider submission.	Choose an alternative model or wait for upstream work to finish.

In-progress counts are approximate. Persisted async tasks are counted only for the most recent three hours, and the system combines Redis atomic counters with task snapshots refreshed about every 10 seconds. Async tasks are additionally retained for up to three minutes before durable persistence is confirmed, so long tasks, snapshot refreshes, and instance restarts can create small count differences without changing durable task state or billing settlement.

Client handling recommendations

Use exponential backoff for 429 and respect Retry-After.
Use Idempotency-Key on async task creation to avoid duplicate tasks during network retries.
Put tenant-side queues in front of batch image, video, and file tasks, then refill from completion events.
Observe long-running tasks through task queries, event streams, or webhooks instead of high-frequency polling.