ขีดจำกัดอัตราการเรียกใช้

ขีดจำกัดอัตราการเรียกใช้

Public API ใช้ขีดจำกัดอัตราการเรียกใช้สองชั้น ทั้งสองขอบเขตอยู่ที่ /api/v1:

1. ก่อนยืนยันตัวตน ตาม IP — ขีดจำกัดคงที่แบบระมัดระวังที่ใช้ก่อนที่คีย์ของคุณจะถูกตรวจสอบด้วยซ้ำ มีไว้เพื่อลดการโจมตีแบบ brute-force/credential-stuffing ต่อเส้นทางการยืนยันตัวตนเอง
2. หลังยืนยันตัวตน ตามคีย์ — ขีดจำกัดที่สำคัญในการใช้งานประจำวัน ผูกกับ API key ของคุณ และแบ่งระดับตามแพ็กเกจขององค์กรของคุณ

ประเภทของ Route

ขีดจำกัดถูกกำหนดตาม ประเภท route ไม่ใช่รายตัว endpoint เพื่อให้ขีดจำกัดคาดเดาได้ทั่วทั้งชุด API ของเรา:

ประเภท	ใช้กับ
read	คำขอ GET/HEAD
search	route ใดๆ ที่ path pattern คงที่มีคำว่า /search
write	ที่เหลือทั้งหมด (POST, PUT, PATCH, DELETE)

การจัดประเภทอิงตาม รูปแบบ route ที่ลงทะเบียนไว้ ไม่ใช่ URL คำขอดิบหรือ query string ดังนั้นจึงไม่สามารถถูกหลอกได้ด้วยการเติม query parameter เข้าไป

ระดับขีดจำกัด (คำขอ/นาที ต่อคีย์)

ระดับ	read	search	write
sandbox	30	15	10
free	60	30	20
starter	120	60	40
growth	300	150	100
plus	600	300	200
pro	1200	600	400
scale	3000	1500	1000
enterprise	6000	3000	2000

ระดับของคุณถูกกำหนดจากแพ็กเกจขององค์กรโดยอัตโนมัติ — ไม่ต้องตั้งค่าใดๆ คีย์ที่มี environment เป็น sandbox จะใช้ระดับ sandbox เสมอ ไม่ว่าแพ็กเกจจริงขององค์กร live ของคุณจะเป็นอะไร

ขีดจำกัดตาม IP ก่อนยืนยันตัวตนคือ 120 read / 60 search / 30 write คำขอต่อนาทีแบบคงที่ เท่ากันสำหรับทุกผู้เรียก — มีไว้เพื่อปกป้องเส้นทางการยืนยันตัวตนเท่านั้น ไม่ได้ใช้บังคับความเป็นธรรมตามแพ็กเกจ

Header

ทุกการตอบกลับจาก /api/v1 จะมี:

RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 1784178600

• RateLimit-Limit — จำนวนคำขอสูงสุดที่อนุญาตในช่วงเวลาปัจจุบัน
• RateLimit-Remaining — จำนวนคำขอที่เหลือในช่วงเวลาปัจจุบัน
• RateLimit-Reset — เวลา Unix timestamp (วินาที) ที่ช่วงเวลาจะรีเซ็ต

เมื่อคำขอถูกปฏิเสธเพราะเกินขีดจำกัด การตอบกลับจะมี header เพิ่มเติมด้วย:

Retry-After: 42

การตอบกลับ

สถานะ	ความหมาย
429 RATE_LIMIT_EXCEEDED	เกินขีดจำกัดสำหรับระดับ/ประเภท route ของคุณ
503 RATE_LIMITER_UNAVAILABLE	ตัวจำกัดอัตราเองไม่พร้อมใช้งาน

Fail closed ไม่ใช่ fail open

หากที่เก็บข้อมูลของตัวจำกัดอัตราไม่สามารถเข้าถึงได้ คำขอจะถูก ปฏิเสธ (503) เสมอ ไม่เคยปล่อยผ่านแบบไม่จำกัดโดยเงียบๆ หากคุณเห็นการเพิ่มขึ้นของ 503 RATE_LIMITER_UNAVAILABLE ให้ชะลอและลองใหม่ — นั่นหมายความว่าโครงสร้างพื้นฐานของเรามีปัญหา ไม่ใช่ว่าคีย์ของคุณทำอะไรผิด

การจัดการขีดจำกัดในระบบของคุณ

• อ่านค่า RateLimit-Remaining และชะลอการเรียกใช้ล่วงหน้า — อย่ารอจนกว่าจะได้ 429
• เมื่อได้ 429 หรือ 503 ให้เคารพค่า Retry-After ก่อนลองใหม่ และใช้ exponential backoff พร้อม jitter สำหรับความล้มเหลวซ้ำๆ
• หากคุณเกินขีดจำกัดของระดับตัวเองอยู่เสมอ การอัปเกรดแพ็กเกจจะเพิ่มเพดานให้ — ไม่ต้องซื้อ “API add-on” แยกต่างหาก