Guide
Rate Limiting and Quota
Concurrency limits, rate limits, quota and account capacity, and backoff retry methods
Rate Limiting and Quota
Platform limits fall into several categories, each with a different symptom when triggered. Identifying which category applies is the key to handling it quickly.
| Limit type | Symptom when triggered | How to handle |
|---|---|---|
| Request frequency (rate limiting) | HTTP 429 "requests too frequent" | Back off and retry; do not retry concurrently |
| Async task concurrency | HTTP 429, task_concurrency_exceeded | Wait for existing tasks to finish before submitting |
| Key quota | Insufficient balance/quota message; the task is not created | Top up, adjust the key quota, or make the request smaller |
| Account balance | A message that the balance is insufficient to cover the estimated consumption for this request | Top up in the wallet |
| Asset capacity | Format and size validation when submitting assets | Fix the file or use image_url |
Request Rate Limits
The platform limits request frequency. Polling too fast, excessive concurrency, or many retries in a short period can all trigger:
{ "error": { "code": "...", "message": "请求过于频繁" } }The HTTP status is 429.
Correct approach:
- After receiving
429, back off: wait a while before sending the next request; do not resend immediately; - Do not try to bypass rate limiting with concurrent requests; that only makes the backoff longer;
- When polling async tasks, use a fixed, reasonable interval (for example, once every few seconds); do not poll with no interval.
Do not blindly retry status codes other than 429:
| Status code | Handling |
|---|---|
429 | Back off as instructed, then retry |
Brief 5xx | Save the RequestId, back off, and retry once |
400 | A parameter problem; fix the request before sending again |
401 | The key is invalid or disabled; check the key |
403 | No permission to access that resource or model |
404 | The resource does not exist; verify the ID |
Async Task Concurrency
Async tasks such as video are subject to a concurrency limit, at both the individual account level and the overall platform level. When the limit is reached, HTTP 429 is returned
with the error code task_concurrency_exceeded, and the message gives "currently N / limit M".
When this happens, you should:
- Keep the IDs of existing tasks; do not discard them;
- Wait for in-flight tasks to reach a terminal state (or query their current status directly);
- Wait, and then have the user actively resubmit; do not retry repeatedly;
- Do not repeatedly submit the same task to "grab" concurrency — that produces duplicate tasks and duplicate charges.
Before submitting in batches, we recommend queue-based management in your business backend: control the number of in-flight tasks rather than submitting everything at once.
Key Quota and Account Balance
Quota and balance are two levels of limits:
| Level | Description |
|---|---|
| Key quota | The usage limit and validity period set for that key in "API Keys" in the console |
| Account balance | The available balance, plan quota, or credits of the entire LocoPal account |
Before submission, async tasks check whether the balance can cover the estimated consumption for this request. If not, a readable message is returned, and no task is created, so this situation incurs no charge.
How to handle:
- Insufficient key quota → adjust the key's quota or validity period in "API Keys";
- Insufficient account balance → top up in "Wallet" or use a plan;
- Estimated consumption too high → lower the resolution or duration, or switch to a smaller model.
We recommend doing a pre-check of the balance in your business backend and giving end users a clear message, rather than passing the platform's error directly to the user.
Asset Limits
The asset API validates uploaded data:
| Limit | Symptom | Handling |
|---|---|---|
| Address format | image_url 必须是可公开下载的 http(s) 地址… | Use an http(s) URL that can be downloaded directly from the public internet |
| Submit only one per call | image_url 与 data_url 只能提交一个 | Keep only one field |
| Data size | 图片数据无效或超过 20MB | Compress the image or use image_url |
| Group type | 素材分组不存在或不是虚拟素材分组 | Images can only be submitted to virtual groups |
| Name length | Group names cannot be empty and must not exceed 64 characters; descriptions must not exceed 300 characters | Fix the name or description |
An incomplete asset review is not an error: the query returns 200 and status is Processing; continue polling with the same asset ID,
and do not resubmit.
Polling Recommendations
Querying async tasks incurs no charge, but polling too frequently triggers rate limiting.
| Task stage | Recommended interval |
|---|---|
| Just submitted (queuing) | Once every few seconds |
| Generating | Once every few seconds to a dozen seconds |
| Reached a terminal state | Stop polling |
Polling should have a maximum total duration. When the limit is reached, stop querying and return the task ID to the user so they can continue querying with the ID later— do not recreate the task.
Idempotency and Duplicate Submissions
The platform does not automatically merge identical requests. Even if the prompt, parameters, and reference assets are completely identical, every active submission creates a new task and a new result, and each is billed separately.
Therefore:
- Use idempotency keys on the business side (order number, business ID) to prevent duplicate submissions caused by users clicking repeatedly;
- Save the task ID in your database immediately after submitting an async task; when the network is interrupted, recover by querying rather than recreating;
- Only when you click "Direct Retry" on the same failed result does it re-execute in place—which likewise produces a new task and new charges.