Rate Limits (การจำกัดการเรียกใช้)
Humansoft Open API จำกัดจำนวนครั้งในการเรียก API เพื่อรักษาเสถียรภาพของระบบและให้ทุกองค์กรใช้งานได้อย่างราบรื่น โดยแบ่งเป็น 2 ระดับ
Overview
| ประเภท | ค่าที่ได้รับ | ช่วงเวลา | เมื่อเกินกำหนด |
|---|---|---|---|
| Rate Limit | 50 ครั้ง | ต่อนาที (นับย้อนหลัง 60 วินาที) | HTTP 429 Too Many Requests จนกว่าจะพ้นช่วงเวลาที่กำหนด |
| Quota | 20,000 ครั้ง | ต่อวัน | เรียก API ไม่ได้จนกว่าโควต้าจะรีเซ็ต |
- ทั้ง Rate Limit และ Quota นับรวมทุก Endpoint ไม่ได้แยกนับตาม API
- ค่าที่องค์กรของคุณได้รับจริงอาจแตกต่างไปจากตารางด้านบน ตรวจสอบได้จาก Response Headers
Response Headers
ทุก Response ที่สำเร็จจะมี Header บอกสถานะการใช้งาน ใช้ Header เหล่านี้ปรับจังหวะการเรียก API ได้โดยไม่ต้องรอจนโดนปฏิเสธ
| Header | Description | ตัวอย่าง |
|---|---|---|
X-RateLimit-Limit | จำนวนครั้งสูงสุดที่เรียกได้ต่อนาที | 50 |
X-RateLimit-Remaining | จำนวนครั้งที่ยังเรียกได้ในช่วง 60 วินาทีล่าสุด (หักรวม Request นี้แล้ว) | 49 |
X-Quota-Limit | จำนวนครั้งสูงสุดที่เรียกได้ต่อวัน | 20000 |
X-Quota-Reset | เวลาที่โควต้ารายวันจะรีเซ็ต (ISO 8601, UTC) | 2026-09-29T00:00:00Z |
Retry-After | จำนวนวินาทีที่ต้องรอก่อนเรียกใหม่ (มีเฉพาะใน Response 429) | 11 |
Example
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 49
X-Quota-Limit: 20000
X-Quota-Reset: 2026-09-29T00:00:00ZHeader ไม่ได้บอกจำนวนโควต้ารายวันที่เหลืออยู่ หากระบบของคุณเรียก API ปริมาณมากในแต่ละวัน ควรนับจำนวนการเรียกไว้ฝั่งระบบของคุณเองด้วย
Rate Limit (ต่อนาที)
ระบบนับจำนวน Request ที่เกิดขึ้น ในช่วง 60 วินาทีล่าสุด ไม่ได้รีเซ็ตทุกต้นนาที ตัวอย่างเช่น
| เวลา | เหตุการณ์ | X-RateLimit-Remaining |
|---|---|---|
| 10:00:00 | Request ที่ 1 | 49 |
| 10:00:49 | Request ที่ 50 | 0 |
| 10:00:50 | Request ที่ 51 → ได้ 429 พร้อม Retry-After: 10 | — |
| 10:01:00 | Request ที่ 1 พ้นช่วง 60 วินาทีแล้ว จึงเรียกได้อีกครั้ง | 0 |
429 Response
เมื่อเรียกเกิน Rate Limit ระบบจะตอบกลับ HTTP status 429 พร้อม Header Retry-After บอกจำนวนวินาทีที่ต้องรอ
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 11
X-RateLimit-Limit: 50{
"statusCode": 429,
"message": "Rate limit is exceeded. Try again in 11 seconds."
}Response 429 มีรูปแบบต่างจาก Response ปกติของ API คือใช้ field statusCode แทน code และไม่มี payload ควรตรวจสอบจาก HTTP status code แทนการอ่านค่า code จาก body
Quota (ต่อวัน)
- Quota คือจำนวนครั้งรวมที่เรียก API ได้ในหนึ่งวัน นับรวมทุก Endpoint
- โควต้าจะรีเซ็ตทุกวันเวลา 00:00 UTC (07:00 น. เวลาประเทศไทย) ดูเวลาที่แน่นอนได้จาก Header
X-Quota-Reset - เมื่อใช้โควต้าครบแล้ว จะเรียก API ไม่ได้จนกว่าจะถึงเวลาใน
X-Quota-Reset
หากต้องการ Rate Limit หรือ Quota มากกว่าที่ได้รับ ติดต่อทีมงานได้ที่ support@humansoft.co.th
Code Examples
ตัวอย่างการเรียก API ที่รอตาม Retry-After แล้วเรียกซ้ำเมื่อได้ 429 (สูงสุด 3 ครั้ง) ใช้ได้กับทุก Endpoint
cURL
# ใช้ -i เพื่อดู Rate Limit Headers ใน Response
curl -i -X GET "https://openapi.humansoft.co.th/api/v1/open-apis/organization/get-list-organization" \
-H "Ocp-Apim-Subscription-Key: YOUR_API_KEY"
# ให้ curl รอตาม Retry-After แล้วเรียกซ้ำอัตโนมัติเมื่อได้ 429 (curl 7.66.0 ขึ้นไป)
curl --retry 3 -X GET "https://openapi.humansoft.co.th/api/v1/open-apis/organization/get-list-organization" \
-H "Ocp-Apim-Subscription-Key: YOUR_API_KEY"Best Practices
- รอตาม
Retry-Afterเสมอ — อย่าเรียกซ้ำทันทีแบบวนลูปเมื่อได้429 - ชะลอเมื่อ
X-RateLimit-Remainingใกล้ 0 — เว้นระยะระหว่าง Request (เช่น ประมาณ 1.2 วินาทีต่อครั้ง จะไม่เกิน 50 ครั้งต่อนาที) - ใช้ Endpoint แบบ Import — เมื่อต้องส่งข้อมูลหลายรายการ ใช้ Endpoint ที่รับข้อมูลเป็นชุด เช่น Import Employee หรือ Import Time Attendance แทนการเรียกทีละรายการ
- Cache Master Data — ข้อมูลที่ไม่ค่อยเปลี่ยน เช่น โครงสร้างองค์กร ควรเก็บ Cache ไว้แทนการเรียกซ้ำ ดูตัวอย่างที่ Getting Started
- กระจายงาน Batch — งานประมวลผลปริมาณมากควรกระจายตลอดวัน เพื่อไม่ให้ใช้ Quota รายวันหมดเร็วเกินไป
Related
- Getting Started - การยืนยันตัวตนและรูปแบบ Response
- API Permissions - สิทธิ์การเข้าถึงของ API Key