API docs · Reliability

Retry guidelines

Which errors to retry and how to back off.

Situation	Retry?	How
Network timeout, dropped connection	Yes	Retry with the same Idempotency-Key
429 rate_limited	Yes	Wait as indicated by Retry-After, then retry
500 internal_error	Yes	Exponential backoff, same idempotency key
422 asset_not_ready	Yes	Wait until the asset is available
400 / 401 / 403 / 404 / 409	No	Fix the request before sending it again
402 insufficient quota or limit	No	Top up, or adjust the key limit or max_budget, before sending it again
Task failed	Depends on the failure code	Follow the suggestion for the failure code; resubmissions need a new idempotency key

Recommended backoff: start at 1 second, double each time, add 0–500 ms of random jitter, and stop after 5 attempts. The platform already retries and fails over between channels internally, so you never need to resubmit the same task.

Node.js

// Use your own unique business ID as the idempotency key: retries after a timeout never create a duplicate task
async function submit(order) {
  const key = `order-${order.id}-v${order.revision}`;
  for (let attempt = 0; attempt < 5; attempt++) {
    try {
      const res = await fetch("https://cn-api.aitoken.tools/v1/videos/generations", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.AITOKEN_API_KEY}`,
          "Idempotency-Key": key,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(order.payload),
      });
      if (res.status < 500 && res.status !== 429) return res.json();
    } catch {
      // Network error: retry with the same key
    }
    await new Promise((r) => setTimeout(r, 2 ** attempt * 1000 + Math.random() * 500));
  }
  throw new Error("submit failed");
}