Rate Limits

Endpoint สำหรับตรวจสอบสลิป (verify) อาจส่ง header rate-limit กลับมาเพื่อให้คุณควบคุมจังหวะการเรียก API ได้ พฤติกรรมนี้เหมือนกันทั้ง API v1 และ v2

เฉพาะ Endpoint ตรวจสอบสลิปเท่านั้น

Rate limit มีผลเฉพาะ route ตรวจสอบสลิปด้านล่างเท่านั้น Endpoint อื่น ๆ (/info, /me, /banks, /bank-accounts*, /qr/generate, /health) ไม่มีการจำกัด และจะไม่ส่ง header เหล่านี้

Endpoint ที่มี Rate Limit

เวอร์ชัน	Endpoint	Budget
v1	GET /verify	bank
v1	POST /verify	bank
v1	POST /verify/truewallet	truewallet
v2	POST /verify/bank	bank
v2	POST /verify/truewallet	truewallet

Budget แยกกัน

การตรวจสอบสลิปธนาคารและ TrueMoney Wallet มี budget rate-limit แยกกันอย่างอิสระ การใช้ budget ของธนาคารจนหมดจะไม่กระทบ budget ของ TrueMoney Wallet และในทางกลับกัน

Headers

เมื่อ rate limit ทำงานอยู่ Response ของการตรวจสอบสลิปจะมี header เหล่านี้:

Header	ความหมาย
X-RateLimit-Limit	ลิมิตปัจจุบันในหน่วย requests ต่อวินาที ค่านี้เปลี่ยนแปลงได้ (dynamic) และอาจต่างกันในแต่ละ request — ให้อ่านจาก Response ทุกครั้ง อย่า hardcode หรือ cache ไว้
X-RateLimit-Remaining	จำนวน request ที่ส่งได้ทันที (burst headroom) ตั้งแต่ 0 จนถึง X-RateLimit-Limit
X-RateLimit-Reset	จำนวนวินาทีนับจากนี้ จนกว่า burst headroom จะกลับมาเต็ม เป็นค่าเชิงเวลาสัมพัทธ์ (relative) ไม่ใช่ Unix timestamp
Retry-After	จำนวนวินาที ที่ต้องรอก่อนลองใหม่ ส่งมาเฉพาะตอน Response เป็น 429 เท่านั้น และมีค่า ≥ 1 เสมอ

Header เป็นตัวเลือก

ให้ถือว่า header เหล่านี้เป็น optional — บาง Response อาจไม่มีมา หากไม่มี header ให้ตีความว่า "ไม่มีข้อมูลลิมิต" ไม่ใช่ "ไม่มีลิมิต"

หลักการทำงานของลิมิต

ลิมิตเป็นหน่วย requests ต่อวินาที และเติมกลับอย่างต่อเนื่อง — ไม่มี fixed window ที่รีเซ็ตตามรอบนาฬิกา ให้อ่าน X-RateLimit-Remaining และ X-RateLimit-Reset จากแต่ละ Response เพื่อควบคุมจังหวะการเรียก

X-RateLimit-Limit เป็นค่า dynamic อาจต่างกันได้ระหว่างสอง request ที่ต่อเนื่องกัน ให้ออกแบบ client ให้ปรับตามค่าที่เห็นจริง ไม่ใช่ยึดค่าคงที่

เมื่อเกินลิมิต (429)

เมื่อคุณเรียกเกินลิมิต API จะตอบกลับด้วย HTTP 429 พร้อม header Retry-After:

v2

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests"
  }
}

v1

{
  "status": 429,
  "message": "rate_limit_exceeded"
}

ให้ทำตาม Retry-After (รอตามจำนวนวินาทีนั้น) แทนการลองใหม่ทันที

Timeout และการ Retry

• ตั้ง timeout ของ client อย่างน้อย 10 วินาที (SDK ของเราตั้งไว้สูงกว่านี้)
• ทำตาม Retry-After ตอน 429 แทนการวน retry ถี่ ๆ
• หลีกเลี่ยงการตั้ง timeout สั้น ๆ ร่วมกับการ retry ทันที

โควต้ารายเดือน (แยกจาก Rate Limit)

Rate limit (ด้านบน) แยกจากโควต้ารายเดือน เมื่อโควต้าหมดจะได้รับ QUOTA_EXCEEDED (v2, 403) / quota_exceeded (v1, 403) — ดูรหัส Error ตรวจสอบโควต้าปัจจุบันได้ที่ GET /info (v2) หรือ GET /me (v1)

บน v2 การตรวจสอบสลิปที่ Branch ของคุณเอง เคยตรวจสอบแล้ว (self-duplicate) จะไม่หักโควต้ารายเดือน (ส่วนสลิปซ้ำจาก Branch อื่น จะหักโควต้า — ดูหัวข้อ "การจัดการสลิปซ้ำ" ใน POST /verify/bank)