Giới hạn tốc độ và hạn mức

Hai loại giới hạn giúp API luôn nhanh cho mọi người:

• Giới hạn tốc độ của khóa: khóa được gửi bao nhiêu yêu cầu mỗi giây, với một đợt tăng đột biến cho các đỉnh ngắn.
• Hạn mức của tổ chức: tất cả các khóa của tổ chức cộng lại được gửi bao nhiêu yêu cầu mỗi phút, mỗi ngày và mỗi tháng.

Cả hai phụ thuộc vào gói của tổ chức. Mọi phản hồi đều cho bạn biết mình đang ở đâu, nên một client hoạt động đúng không bao giờ phải đoán.

Giới hạn tốc độ của khóa

Mỗi khóa có một tốc độ ổn định và một đợt tăng đột biến. Đợt tăng đột biến cho phép bạn gửi ngần ấy yêu cầu cùng lúc; sau đó, yêu cầu được chấp nhận với tốc độ ổn định.

Hạng được xác định theo gói của tổ chức. GET /v1/me cho biết hạng, tốc độ và đợt tăng đột biến của khóa gọi nó (rate_limit). Giới hạn áp dụng cho toàn bộ khóa, bất kể có bao nhiêu máy chủ API phục vụ yêu cầu của bạn.

Các endpoint dạng luồng, POST /v1/chat (có hoặc không có "stream": true) và GET /v1/jobs/stream, nằm ngoài giới hạn tốc độ của khóa: chúng không tiêu hao giới hạn đó, và header RateLimit của chúng không có mục "key". Chúng vẫn được tính vào hạn mức của tổ chức, mỗi yêu cầu một lần, lúc yêu cầu bắt đầu. Câu hỏi có giới hạn riêng, được mô tả bên dưới.

Hạn mức của tổ chức

Gói có thể đặt hạn mức yêu cầu cho tổ chức: mỗi phút, mỗi ngày và mỗi tháng. Các khung thời gian là chu kỳ lịch theo UTC: một phút bắt đầu ở giây :00, một ngày lúc 00:00 UTC, một tháng vào ngày đầu tiên lúc 00:00 UTC. Mọi yêu cầu với khóa hoặc token OAuth của tổ chức đều được tính, trên bất kỳ địa chỉ nào. Yêu cầu dạng luồng được tính một lần, lúc bắt đầu, dù kéo dài bao lâu; khi hạn mức đã dùng hết, yêu cầu đó bị từ chối với 429 như mọi yêu cầu khác. Yêu cầu bị từ chối với 429 không được tính.

Các header

Mọi phản hồi cho yêu cầu có khóa đều mang các giới hạn áp dụng cho nó:

RateLimit-Policy: "key";q=100;w=5, "minute";q=1200;w=60, "day";q=200000;w=86400
RateLimit: "key";r=87;t=1, "minute";r=1150;t=23, "day";r=180311;t=40213
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1

RateLimit-Policy và RateLimit tuân theo bản thảo IETF RateLimit header fields for HTTP. Mỗi mục là một giới hạn:

X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset báo cáo giới hạn chặt nhất trong số này ở dạng đơn giản hơn, dành cho client được viết trước khi có RateLimit. X-RateLimit-Reset tính bằng giây.

Khi chạm giới hạn

API trả về 429 Too Many Requests với header Retry-After tính bằng giây:

{
  "detail": "the organization has used its API request quota for this period",
  "error": {
    "code": "api.quota_exceeded",
    "message": "the organization has used its API request quota for this period",
    "details": {"quota": "day", "limit": 200000, "reset_at": "2026-10-25T00:00:00Z", "retry_after": 40213},
    "request_id": "01JB7…"
  }
}

Hãy chờ hết Retry-After rồi lặp lại yêu cầu. Lặp lại POST và PATCH với cùng Idempotency-Key. Các hàm hỗ trợ thử lại trong Lỗi làm cả hai việc này.

Các giới hạn khác của gói cũng trả về 429 với Retry-After, ví dụ số câu hỏi mỗi ngày (limits.questions) hoặc số câu trả lời đang được tạo cùng lúc (limits.concurrent_answers). Hãy xử lý chúng theo cùng cách.

Cách không vượt giới hạn

• Đọc RateLimit và giảm tốc khi r xuống thấp, thay vì chờ tới 429.
• Dàn trải công việc khối lượng lớn theo thời gian, và dùng endpoint lô ở nơi có: một lô 100 tài liệu là một yêu cầu.
• Đừng thăm dò thay đổi trong một vòng lặp dày đặc. Hãy đăng ký webhook, hoặc đọc nguồn cấp sự kiện vài giây một lần.
• Chạy các worker song song với một bộ giới hạn dùng chung. Nhiều tiến trình dùng một khóa thì chia sẻ một giới hạn tốc độ.
• Hỏi đầu mối liên hệ của bạn tại Sursa về hạng cao hơn nếu tích hợp của bạn cần nhiều hơn.