> ## Documentation Index
> Fetch the complete documentation index at: https://powower.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Async Task Polling: 429 / 5xx Handling Convention

> How to handle 429 rate limits and 5xx transient failures when polling async task status endpoints.

This document defines the expected behavior of asynchronous task (video, image generation, etc.) status query endpoints under `429` and `5xx` responses, as a reference for client-side polling implementations.

## Scope

* `GET /v1/videos/:task_id`
* `GET /kling/v1/videos/:action/:task_id`
* `GET /kling/v1/images/:action/:task_id`
* `GET /vidu/ent/v2/tasks/:task_id/creations`
* `GET /minimax/v1/query/video_generation`
* `GET /minimax/v2/query/video_generation/:task_id`
* `GET /byteplus/api/v3/contents/generations/tasks/:id`

## 429 Too Many Requests

* Semantics: transient rate limiting (request frequency, concurrency, or per-group load) **does NOT mean the task has failed**.
* `Retry-After`: baze platform guarantees that **all** `429` responses carry a `Retry-After` response header with an integer second value (default `5`). If the downstream provider has explicitly set this header, its value is preserved as-is.
* Expected client handling:
  1. Read `Retry-After`, wait for that many seconds, then issue the next query.
  2. Do **not** treat `429` as a terminal task status, and do not count it towards any "task failure" counter.
  3. If `Retry-After` is missing (e.g. stripped by an opaque proxy), fall back to a default `5` second backoff.

## 5xx Internal Error / Gateway Error / Service Unavailable

* Semantics: a transient failure in the platform or upstream provider. The task may still be running normally upstream, or it may have already failed — **a `5xx` response does not directly imply the task's terminal state**.
* Expected handling: **fail fast or retry with a bounded limit**. Do not retry indefinitely.
  1. Exponential backoff is recommended (e.g. `5s`, `10s`, `20s`… with an upper bound of `60s`).
  2. Enforce a maximum retry count or total duration; once the threshold is exceeded, stop polling and surface a clear error to the user while preserving the `task_id` so it can be queried again later once the service recovers.
  3. Do **not** keep retrying forever just because you did not receive a `status` field — the absence of a status is not the same as "still queued".
* Response body convention: async task query endpoints still return a JSON response body on `5xx`, with a `status` field and error details to distinguish "endpoint error" from "task still queued", for example:

```json theme={null}
{
  "code": "query_failed",
  "message": "query task failed",
  "data": null,
  "status": "running"
}
```

* `Retry-After`: async task query endpoints also return `Retry-After` on `5xx` (default `5` seconds), but this header is **globally guaranteed only for `429`**. Clients should not rely on `5xx` responses always including it.

## Other 4xx

`4xx` responses other than `429` (e.g. `task_not_exist`, parameter errors, auth failures) are deterministic errors. Stop polling immediately and handle them according to the error details.

## Guarantee Matrix

| Status code | Implies task failure? | Response body includes `status` | `Retry-After` | Client recommendation |
| - | - | - | - | - |
| `200` | No | Yes | No | Use `status` to decide whether to keep polling |
| `429` | No | Depends on the endpoint | **Guaranteed present** | Wait according to `Retry-After` then retry |
| `5xx` (async query endpoints) | No | Yes (`running`) | Returned, but not globally guaranteed | Bounded retries with exponential backoff; abort above threshold |
| Other `4xx` | Yes (deterministic error) | No | No | Stop polling and handle the error |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.