Hàng chờ và nghẽn

Tóm tắt — Câu trả lời submit cho biết bao nhiêu run của bạn đang chạy, bao nhiêu đang chờ, và giới hạn của bạn. GET /v2/queue cho xem các số đó ngay lúc này. GET /v2/queue/log trả các số theo từng phút hoặc từng giờ, GET /v2/queue/refusals liệt kê các lần submit bị từ chối, và GET /v2/queue/episodes liệt kê các đợt nghẽn. Đăng ký queue.congestion_started và queue.congestion_ended để chuyển sang phương án dự phòng (fallback) sớm.

Bạn chỉ thấy số của chính product mình. Key test và key live tính riêng.

Từ ngữ#

Giới hạn hằng ngày theo end user (end_user_cap_reached) không phải là bị từ chối: nó nói về một người, không phải về product của bạn.

Header trên mỗi lần submit#

Câu trả lời của POST /v2/styles/{style}, POST /v2/runs và POST /v2/jobs có ba header: dù submit được nhận, được phát lại (replay) hay bị từ chối.

HTTP/1.1 202
X-Concurrency-Limit: 20
X-Concurrency-Running: 20
X-Concurrency-Waiting: 6

Khi Running và Waiting cùng chạm Limit, run priority mới bị từ chối: 429 product_busy (Jobs API: PRODUCT_BUSY) kèm Retry-After: 5. Run Relax không bao giờ bị từ chối vì lý do này; chúng chờ.

• Submit bị trả lỗi trước khi xét tới giới hạn (body sai, style không có, key sai) thì không có các header này.
• Coi các header là không bắt buộc: nếu tạm thời không đọc được số, câu trả lời sẽ không kèm chúng.

Hàng chờ lúc này#

GET /v2/queue trả số của product ngay lúc này, theo product và chế độ (test/live) của key.

curl https://api.wandura.ai/v2/queue -H "Authorization: Bearer $WANDURA_KEY"

{
  "object": "queue_state",
  "product": "prod_…",
  "livemode": true,
  "concurrency_limit": 20,
  "running": 20,
  "waiting": 6,
  "queue_limit": 20,
  "accepted_this_minute": 41,
  "per_minute_limit": 60,
  "refusals": { "last_15m": 0, "last_24h": 3 },
  "at": "2026-10-15T09:30:12.000Z"
}

Nhật ký hàng chờ#

GET /v2/queue/log trả các số theo thời gian, mỗi ô (bucket) là một phút hoặc một giờ, cũ nhất trước.

• Một khoảng dài tối đa 7 ngày nếu theo phút, 90 ngày nếu theo giờ. Ô phút được giữ 7 ngày, ô giờ 90 ngày.
• Ô không có hoạt động thì bị bỏ ra.
• Một phút hiện ra khoảng một phút sau khi nó kết thúc. Giờ hiện tại được điền dần.
• Giá trị sai trả 400 invalid_request, thông điệp nói rõ giá trị nào.

curl "https://api.wandura.ai/v2/queue/log?granularity=minute&from=2026-10-15T09:00:00Z" \
  -H "Authorization: Bearer $WANDURA_KEY"

{
  "object": "list",
  "product": "prod_…",
  "livemode": true,
  "granularity": "minute",
  "from": "2026-10-15T09:00:00.000Z",
  "to": "2026-10-15T09:30:00.000Z",
  "data": [
    {
      "object": "queue_log_bucket",
      "bucket": "2026-10-15T09:29:00.000Z",
      "accepted": 38,
      "refusals": { "product_busy": 2, "rate_limited": 0 },
      "max_running": 20,
      "max_waiting": 20,
      "concurrency_limit": 20,
      "ended": 17,
      "median_wait_ms": 41000,
      "median_duration_ms": 96000
    }
  ]
}

Bị từ chối#

GET /v2/queue/refusals liệt kê các lần submit bị từ chối, mới nhất trước. Được giữ 30 ngày.

{
  "object": "list",
  "data": [
    {
      "object": "queue_refusal",
      "id": "5821",
      "at": "2026-10-15T09:29:41.204Z",
      "reason": "product_busy",
      "style": "sty_…",
      "end_user_id": "user_42",
      "retry_after_s": 5,
      "livemode": true
    }
  ],
  "has_more": false
}

reason là product_busy (hết suất chạy và hàng chờ đầy) hoặc rate_limited (vượt số run mỗi phút). end_user_id là null khi lệnh gọi không gửi. Dùng nó để biết người dùng nào của bạn bị ảnh hưởng.

Đợt nghẽn#

Wandura kiểm product của bạn mỗi phút. Mỗi loại nghẽn mở một đợt riêng, nên nhiều đợt có thể cùng mở.

• Cùng một loại không bắt đầu lại trong 30 phút sau khi hết.
• Chỉ key live: key test không bao giờ mở đợt nghẽn.
• Thời gian chạy tính từ lúc bắt đầu tới lúc kết thúc. Không tính lúc chờ trước đó.

GET /v2/queue/episodes liệt kê các đợt nghẽn, mới nhất trước. Nhận cùng limit và before như danh sách bị từ chối.

{
  "object": "list",
  "data": [
    {
      "object": "congestion_episode",
      "id": "184",
      "product": "prod_…",
      "livemode": true,
      "kind": "refusing",
      "status": "ended",
      "started_at": "2026-10-15T09:31:00.000Z",
      "ended_at": "2026-10-15T09:52:00.000Z",
      "duration_s": 1260,
      "start": { "running": 20, "waiting": 20, "concurrency_limit": 20, "refusals_5m": 3, "refusals_10m": 3, "runs_ended_15m": 24, "median_duration_ms": 95000 },
      "end": { "running": 9, "waiting": 0, "concurrency_limit": 20, "refusals_5m": 0, "refusals_10m": 0, "runs_ended_15m": 30, "median_duration_ms": 88000 },
      "affected": { "refusals": 7, "runs_accepted": 212, "runs_ended": 205 }
    }
  ],
  "has_more": false
}

Event webhook#

Mỗi đợt nghẽn được gửi hai lần tới webhook của product:

• queue.congestion_started khi đợt bắt đầu.
• queue.congestion_ended khi đợt hết.

Đây là event phải tự đăng ký (opt-in): webhook của bạn chỉ nhận khi danh sách event của nó có tên hai event này. Muốn bật, hãy nhờ Wandura thêm cả hai event vào webhook của product. Các event khác của bạn giữ nguyên.

data là đợt nghẽn đúng như lúc event được tạo. Không có sequence, vì event không thuộc run nào. Chữ ký, gửi lại, Wandura-Event-Id và Wandura-Event-Type giống event của run: xem Webhook.

{
  "id": "evt_…",
  "object": "event",
  "type": "queue.congestion_started",
  "created_at": "2026-10-15T09:31:00.412Z",
  "data": {
    "object": "congestion_episode",
    "id": "184",
    "product": "prod_…",
    "livemode": true,
    "kind": "refusing",
    "status": "open",
    "started_at": "2026-10-15T09:31:00.000Z",
    "ended_at": null,
    "duration_s": null,
    "start": { "running": 20, "waiting": 20, "concurrency_limit": 20, "refusals_5m": 3, "refusals_10m": 3, "runs_ended_15m": 24, "median_duration_ms": 95000 },
    "end": null,
    "affected": null
  }
}

• Ghép lúc bắt đầu với lúc hết theo data.id. Hiếm khi, event hết tới trước event bắt đầu: hãy tin data.status.
• Event là tín hiệu nhanh. Muốn có sổ đầy đủ, đọc GET /v2/queue/episodes.

Nên làm gì#

• Theo dõi header. Khi X-Concurrency-Waiting tăng dần tới X-Concurrency-Limit, hãy gửi chậm lại hoặc đưa việc mới sang fallback trước khi bị từ chối.
• Làm theo event. Khi nhận queue.congestion_started, chuyển sang fallback: ngay lập tức với refusing, sớm với near_full, còn với slow thì báo người dùng hoặc dùng đường nhanh hơn. Khi nhận queue.congestion_ended cùng loại, chuyển về lại.
• Khi gặp 429 (product_busy, gateway_rate_limited; Jobs API PRODUCT_BUSY, RATE_LIMITED): không có run nào được tạo, nên gửi request đó sang fallback không thể chạy hai lần. Muốn thử lại với Wandura, chờ đúng Retry-After giây (cộng thêm chút jitter) rồi gửi lại với cùng Idempotency-Key.
• Khi gặp 503 service_unavailable (Jobs API SERVICE_UNAVAILABLE): không có gì được tạo hay tính tiền. Thử lại sau Retry-After với cùng Idempotency-Key.
• Poll thong thả. Khi product đang nghẽn, run chờ lâu hơn. Poll mỗi run 5–10 giây một lần, hoặc tốt hơn, dùng webhook. Poll nhanh hơn không làm run bắt đầu sớm hơn.
• Cần thêm chỗ? Nhật ký hàng chờ và danh sách bị từ chối cho thấy bạn chạm giới hạn khi nào và bao nhiêu lần. Gửi chúng cho Wandura để được nâng số suất chạy hoặc số run mỗi phút của product.

Khi chính Wandura gặp sự cố, thông báo nằm ở wandura.instatus.com.

Xem thêm: Lỗi · Khái niệm: giới hạn · Jobs API: giới hạn.