ขีดจำกัดอัตราการเรียกและโควตา

ขีดจำกัดสองประเภทช่วยให้ API ตอบสนองได้เร็วสำหรับทุกคน:

• ขีดจำกัดอัตราการเรียก ของคีย์ คือจำนวนคำขอต่อวินาทีที่คีย์ส่งได้ พร้อมช่วงพุ่งสูง (burst) สำหรับจังหวะที่มีคำขอมากในเวลาสั้น
• โควตา ขององค์กร คือจำนวนคำขอที่ทุกคีย์ขององค์กรรวมกันส่งได้ต่อนาที ต่อวัน และต่อเดือน

ทั้งสองอย่างขึ้นอยู่กับแพ็กเกจขององค์กร ทุกการตอบกลับบอกสถานะปัจจุบันของคุณ ไคลเอ็นต์ที่ทำงานถูกต้องจึงไม่ต้องคาดเดาเลย

ขีดจำกัดอัตราการเรียกของคีย์

แต่ละคีย์ได้อัตราคงที่และช่วงพุ่งสูง ช่วงพุ่งสูงทำให้ส่งคำขอได้ตามจำนวนนั้นในครั้งเดียว หลังจากนั้นระบบจะรับคำขอตามอัตราคงที่

ระดับมาจากแพ็กเกจขององค์กร GET /v1/me แสดงระดับ อัตรา และช่วงพุ่งสูงของคีย์ที่เรียกใช้ (rate_limit) ขีดจำกัดนี้ใช้กับคีย์ทั้งคีย์ ไม่ว่าจะมีเซิร์ฟเวอร์ API กี่เครื่องให้บริการคำขอของคุณ

เอนด์พอยต์แบบสตรีม ได้แก่ POST /v1/chat (ทั้งที่มีและไม่มี "stream": true) และ GET /v1/jobs/stream อยู่นอกขีดจำกัดอัตราการเรียกของคีย์ คำขอเหล่านี้ไม่ถูกนับในขีดจำกัดนั้น และเฮดเดอร์ RateLimit ของคำขอเหล่านี้ไม่มีรายการ "key" แต่ยังนับรวมในโควตาขององค์กรคำขอละหนึ่งครั้งเมื่อคำขอเริ่มต้น คำถามมีขีดจำกัดของตัวเองซึ่งอธิบายไว้ด้านล่าง

โควตาขององค์กร

แพ็กเกจกำหนดโควตาคำขอขององค์กรได้ ทั้งต่อนาที ต่อวัน และต่อเดือน กรอบเวลาเป็นช่วงตามปฏิทินใน UTC: นาทีเริ่มที่วินาที :00 วันเริ่มเวลา 00:00 UTC และเดือนเริ่มวันแรกของเดือนเวลา 00:00 UTC ทุกคำขอที่ใช้คีย์หรือโทเค็น OAuth ขององค์กรนับรวมทั้งหมด ไม่ว่าจะส่งไปยังที่อยู่ใด คำขอแบบสตรีมนับเพียงครั้งเดียวเมื่อเริ่มต้น ไม่ว่าจะใช้เวลานานเท่าใด เมื่อโควตาหมดแล้ว คำขอแบบสตรีมก็ถูกปฏิเสธด้วย 429 เหมือนคำขออื่น คำขอที่ถูกปฏิเสธด้วย 429 ไม่นับรวม

เฮดเดอร์

ทุกการตอบกลับของคำขอที่ใช้คีย์มีขีดจำกัดที่ใช้กับคำขอนั้น:

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 และ RateLimit เป็นไปตามร่างมาตรฐาน IETF RateLimit header fields for HTTP แต่ละรายการคือขีดจำกัดหนึ่งรายการ:

X-RateLimit-Limit X-RateLimit-Remaining และ X-RateLimit-Reset รายงานขีดจำกัดที่เข้มงวดที่สุดในบรรดาขีดจำกัดเหล่านี้ในรูปแบบที่ง่ายกว่า สำหรับไคลเอ็นต์ที่เขียนขึ้นก่อนจะมี RateLimit โดย X-RateLimit-Reset มีหน่วยเป็นวินาที

เมื่อถึงขีดจำกัด

API ตอบกลับ 429 Too Many Requests พร้อมเฮดเดอร์ Retry-After เป็นวินาที:

{
  "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…"
  }
}

รอตาม Retry-After แล้วส่งคำขอซ้ำ ส่ง POST และ PATCH ซ้ำด้วย Idempotency-Key เดิม ฟังก์ชันช่วยลองใหม่ใน ข้อผิดพลาด ทำทั้งสองอย่างให้

ขีดจำกัดอื่นของแพ็กเกจก็ตอบกลับ 429 พร้อม Retry-After เช่นกัน เช่น จำนวนคำถามต่อวัน (limits.questions) หรือจำนวนคำตอบที่กำลังสร้างพร้อมกัน (limits.concurrent_answers) ให้จัดการด้วยวิธีเดียวกัน

การใช้งานให้อยู่ภายในขีดจำกัด

• อ่าน RateLimit และชะลอความเร็วเมื่อ r เหลือน้อย แทนการรอจนได้ 429
• กระจายงานปริมาณมากออกไปตามเวลา และใช้เอนด์พอยต์แบบชุดในที่ที่มีให้ใช้ ชุดเอกสาร 100 รายการนับเป็นคำขอเดียว
• อย่าโพลหาการเปลี่ยนแปลงในลูปที่ถี่เกินไป ให้สมัครรับ เว็บฮุก หรืออ่าน ฟีดอีเวนต์ ทุกสองสามวินาที
• รันเวิร์กเกอร์แบบขนานโดยใช้ตัวจำกัดอัตราการเรียกร่วมกัน โปรเซสหลายตัวที่ใช้คีย์เดียวกันใช้ขีดจำกัดอัตราการเรียกเดียวกัน
• สอบถามผู้ประสานงานของคุณที่ Sursa เรื่องระดับที่สูงขึ้น หากระบบที่เชื่อมต่อต้องการมากกว่านี้