การจำกัดอัตราการเรียก (Rate Limit) และการควบคุมปริมาณ

API การจำกัดอัตรา 429 การควบคุมปริมาณ

บทความนี้อธิบายว่า API ของ ReceiptRoller รับคำขอได้มากเพียงใด จะได้รับการตอบกลับแบบใดเมื่อถึงขีดจำกัด และวิธีควบคุมปริมาณการเรียกจากไคลเอนต์ของคุณให้อยู่ในระดับที่เหมาะสม API ของร้านค้าและบัญชีธุรกิจที่เรียกด้วยแอ็กเซสโทเคนของแอปจะอยู่ภายใต้โควตารายเดือนตามแพ็กเกจของบัญชีธุรกิจ นอกจากนี้ บางเอนด์พอยต์ เช่น การรับใบเสร็จหรือการส่งใบเสร็จจากเครื่องพิมพ์ ยังมีขีดจำกัดระยะสั้นของตัวเองด้วย

API ที่เรียกด้วยโทเคนของแอป

การเรียกเอนด์พอยต์ /api/v1/... ด้วยแอ็กเซสโทเคนที่ออกให้กับบัญชีธุรกิจ (สินค้า ยอดขาย การจอง ฯลฯ) จะถูกนับรวมในโควตารายเดือนของบัญชีธุรกิจนั้น

แพ็กเกจจำนวนการเรียก API ที่รวมอยู่ต่อเดือนค่าแนะนำต่อนาที
Starter5,00060
Growth50,000300
Enterprise500,0001,000
  • แพ็กเกจ Basic และช่วงทดลองใช้ฟรีไม่รวมการเข้าถึง API
  • หนึ่งเดือนนับตั้งแต่วันที่ 1 ถึงวันสุดท้ายของเดือนตามเวลาญี่ปุ่น
  • การเรียกจากแอปของ ReceiptRoller เองจะไม่ถูกนับ นับเฉพาะแอปของบุคคลภายนอกเท่านั้น
  • การเรียกจะไม่ถูกหยุดเมื่อถึงโควตา และไม่มีค่าใช้จ่ายสำหรับการเรียกที่เกินโควตา เมื่อบัญชีธุรกิจใช้ถึง 80% และ 100% ของโควตา ระบบจะแจ้งเจ้าของบัญชีทางอีเมล
  • คำขออาจถูกจำกัดเมื่อบัญชีธุรกิจเรียกเกินสองเท่าของโควตารายเดือน หรือส่งคำขอเกินค่าแนะนำต่อนาที
  • การตอบกลับจะไม่มี header ด้านการจำกัดอัตรา เช่น X-RateLimit-Limit, X-RateLimit-Remaining หรือ X-RateLimit-Reset
  • เอนด์พอยต์โทเคน POST /api/v1/auth/token ไม่มีขีดจำกัดสำหรับการแลก authorization code (authorization_code) หรือรีเฟรชโทเคน (refresh_token)

เจ้าของบัญชีธุรกิจสามารถดูจำนวนการเรียกของเดือนนี้แยกตามวันและตามแอปได้ที่หน้าการใช้งานแพ็กเกจ ดูรายละเอียดที่ วิธีอ่านหน้าการใช้งานแพ็กเกจ (ภาษาอังกฤษ)

เอนด์พอยต์ที่มีขีดจำกัดของตัวเอง

เอนด์พอยต์ต่อไปนี้จำกัดจำนวนคำขอในช่วง 1 นาทีล่าสุด (สำหรับอีเมลคือ 1 ชั่วโมงล่าสุด) โดยนับตาม IP address ของไคลเอนต์ หรือตามการจับคู่ในคอลัมน์ "นับตาม"

เอนด์พอยต์ขีดจำกัดนับตาม
POST /api/v1/devices/printer/receipts, POST /api/v1/devices/printer/receipts/{token}/ad-printed300 ครั้งต่อนาทีIP address
GET /api/v1/apps/{shopId}/ads30 ครั้งต่อนาทีIP address
GET /api/v1/receipt-ad60 ครั้งต่อนาทีIP address
GET /api/v1/terminals/{publicTerminalId}/last-receipt, GET /api/v1/rx/{claimToken}10 ครั้งต่อนาทีIP address และเทอร์มินัล (หรือโทเคน)
POST /api/v1/terminals/{publicTerminalId}/claim, POST /api/v1/rx/{claimToken}/claim3 ครั้งต่อนาที (นับรวมใน 10 ครั้งต่อนาทีข้างต้นด้วย)IP address และเทอร์มินัล (หรือโทเคน)
POST /api/v1/user/terminals/{publicTerminalId}/claim, POST /api/v1/user/rx/{claimToken}/claim3 ครั้งต่อนาทีIP address และเทอร์มินัล (หรือโทเคน)
POST /api/v1/rx/{claimToken}/claim แบบส่งทางอีเมล3 ครั้งต่อชั่วโมงอีเมลปลายทาง

การลงเวลาเข้าออกงาน (POST /api/v1/stores/{storeId}/timecards/punch) ไม่มีการจำกัดอัตรา แต่หากใส่ PIN ผิดติดกัน 5 ครั้งสำหรับบุคคลเดียวกัน การลงเวลาของบุคคลนั้นจะถูกล็อก 15 นาที และการเรียกจะได้ 429 พร้อม {"error": "pin_locked", "message": "...", "lockedUntil": "..."}

ขั้นตอนการลงชื่อเข้าใช้ของแอปทางการของ ReceiptRoller (การแลก ID token การสร้างบัญชีแบบไม่ระบุตัวตน) ก็มีขีดจำกัดของตัวเองเช่นกัน แต่ไม่มีผลกับการแลก authorization code และรีเฟรชโทเคนที่แอปของนักพัฒนาใช้

การตอบกลับเมื่อถึงขีดจำกัด

สถานะจะเป็น 429 Too Many Requests เสมอ ส่วนที่เหลือของการตอบกลับขึ้นอยู่กับขีดจำกัดที่ถึง

  • ขีดจำกัดของบัญชีธุรกิจสำหรับการเรียกด้วยโทเคนของแอป: body เป็น JSON ที่มี error และ message พร้อม header Retry-After โดย error เป็น rate_limited เมื่อเกินค่าแนะนำต่อนาที (Retry-After: 60) หรือ monthly_limit_exceeded เมื่อเกินสองเท่าของโควตารายเดือน (Retry-After คือจำนวนวินาทีจนถึงต้นเดือนถัดไปตามเวลาญี่ปุ่น)
  • การส่งจากเครื่องพิมพ์ (/api/v1/devices/printer/...), GET /api/v1/apps/{shopId}/ads และขีดจำกัด 3 ครั้งต่อนาทีของแต่ละ .../claim: มี header Retry-After: 60 และ body เป็นข้อความ Too many requests. Please try again in a minute.
  • ขีดจำกัดเฉพาะเอนด์พอยต์อื่น ๆ (last-receipt, GET /api/v1/rx/{claimToken}, GET /api/v1/receipt-ad, 10 ครั้งต่อนาทีของ claim และ 3 ครั้งต่อชั่วโมงของอีเมล): ได้ 429 ที่ไม่มี body และไม่มี Retry-After
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{ "error": "rate_limited", "message": "Too many requests for this business account. Try again in a minute." }

ให้ตรวจจับ 429 จาก status code ก่อน แล้วจึงใช้ error (หากมี) เพื่อแยกแยะกรณี

การควบคุมปริมาณการเรียกให้เหมาะสม

  • งานจำนวนมากให้ส่งทีละคำขอตามลำดับ อย่ายิงคำขอหลายร้อยรายการพร้อมกันด้วย Promise.all หรือวิธีที่คล้ายกัน
  • ใช้เอนด์พอยต์แบบรายการแทนการดึงทีละรายการ เช่น รายการสินค้า GET /api/v1/products จะส่งสินค้าทั้งหมดกลับมาในการตอบกลับครั้งเดียว การซิงก์จึงดึงเพียงครั้งเดียวแล้วจับคู่ในระบบของคุณ
  • แคชข้อมูลที่ไม่ค่อยเปลี่ยน เช่น ข้อมูลร้านค้าและข้อมูลหลักของสินค้า
  • ใช้ Webhook แทนการ polling เพื่อติดตามการเปลี่ยนแปลง (ภาพรวมของ Webhook)

แนวทางการลองเรียกใหม่

  • 429 ที่มี rate_limited หรือ 429 อื่น ๆ: หากมี Retry-After ให้รอตามจำนวนวินาทีนั้นแล้วส่งใหม่ หากไม่มี ให้รอประมาณ 1 นาที เนื่องจากขีดจำกัดเหล่านั้นนับช่วง 1 นาทีล่าสุด
  • 429 ที่มี monthly_limit_exceeded: อย่าลองใหม่อัตโนมัติ การเรียกจะถูกรับอีกครั้งตั้งแต่ต้นเดือนถัดไป หรือเมื่อบัญชีธุรกิจเปลี่ยนไปใช้แพ็กเกจที่มีโควตามากขึ้น
  • 503 และ 5xx อื่น ๆ, timeout และข้อผิดพลาดในการเชื่อมต่อ: ลองใหม่สองสามครั้ง โดยเพิ่มเวลารอเป็นสองเท่าในแต่ละครั้งและเพิ่ม jitter แบบสุ่ม
  • 400, 401, 403, 404: การส่งคำขอเดิมซ้ำจะได้ผลเหมือนเดิม สำหรับ 401 ให้รีเฟรชโทเคนแล้วลองใหม่หนึ่งครั้ง
  • การส่ง POST สำหรับสร้างข้อมูลซ้ำหลังเกิด timeout อาจทำให้เกิดข้อมูลซ้ำ เนื่องจากไม่มี header Idempotency-Key แบบทั่วไป ให้ตรวจสอบว่ารายการถูกสร้างแล้วหรือยัง (เช่น ดูในรายการ) ก่อนส่งใหม่
async function callWithRetry(send, maxAttempts = 5) {
  for (let attempt = 1; ; attempt++) {
    const response = await send();
    const retryable = response.status === 429 || response.status >= 500;
    if (!retryable || attempt === maxAttempts) return response;

    const retryAfter = Number(response.headers.get("Retry-After"));
    if (response.status === 429 && retryAfter > 3600) return response; // ถึงโควตารายเดือนแล้ว: หยุดลองใหม่
    const backoff = Math.min(2 ** attempt, 60) * (0.75 + Math.random() * 0.5);
    const waitSeconds = response.status === 429 ? (retryAfter || 60) : backoff;
    await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));
  }
}

คู่มือที่เกี่ยวข้อง

วันที่เผยแพร่: 2569-04-27 วันที่อัปเดต: 2569-11-14
เกี่ยวกับหัวข้อนี้
Developer API
ดูรายละเอียดฟีเจอร์
แท็ก
API (22) OAuth (15) Android (10) iOS (9) Webhook (8) api (7) oauth (5) getting-started (4) การลงทะเบียนแอป (4) การแก้ปัญหา (4)
บทความที่เกี่ยวข้อง