Telm מודדת את ה־API בשתי דרכים: מגבלת קצב לדקה (תקרת התפרצות) ומכסה יומית (התקציב הכולל שלכם ליום ה־UTC). שתיהן מתרחבות עם התוכנית. כל תגובה נמדדת מחזירה X-Quota-Limit, X-Quota-Used ו־X-Quota-Reset כך שאתם תמיד יודעים את התקציב הנותר שלכם, ושתי המגבלות מחזירות 429 עם כותרת Retry-After כאשר חורגים.
1שתי מגבלות: קצב לדקה ומכסה יומית
יש שתי תקרות נפרדות. מגבלת הקצב לדקה מגבילה כמה בקשות אתם יכולים לבצע בתוך כל דקה בודדת, ומחליקה התפרצויות. המכסה היומית היא התקציב הכולל שלכם: היא מגבילה כמה קריאות נמדדות אתם יכולים לבצע לאורך כל יום ה־UTC.
הן בלתי תלויות. אתם יכולים להגיע למגבלת הדקה בעוד יש לכם עדיין שפע מכסה יומית (אתם פשוט שולחים מהר מדי), או למצות את המכסה היומית שלכם בעוד אתם הרבה מתחת למגבלת הדקה (ניצלתם את היום). שתיהן מחזירות סטטוס 429, אך מסיבות שונות — בדקו את קוד השגיאה בגוף כדי להבחין ביניהן.
- מגבלת קצב לדקה — תקרת התפרצות, מתאפסת בכל דקה.
- מכסה יומית — סך הקריאות הנמדדות שלכם ליום, מתאפסת בחצות UTC.
- המכסה נספרת פעם אחת לכל חשבון, משותפת לכל המפתחות שלכם.
2מכסה יומית לפי תוכנית
המכסה היומית שלכם היא מספר קריאות ה־API הנמדדות שאתם יכולים לבצע ליום UTC, והיא תלויה בתוכנית שלכם. המונה משותף לכל המפתחות שלכם ועוקב אחר התוכנית הטובה ביותר מבין הקבוצות שאתם מנהלים — ללא מנוי בתשלום, אתם בשכבת Free.
החלון הוא יום הלוח של UTC, כך שמונה השימוש שלכם מתאפס לאפס בחצות UTC. בדיקת ספאם באצווה עולה קריאה אחת לכל פריט באצווה, לא קריאה אחת לכל הבקשה.
- Free — 100 קריאות ליום.
- Basic — 1,000 קריאות ליום.
- Pro — 10,000 קריאות ליום.
- Business — 50,000 קריאות ליום.
3מגבלת קצב לדקה לפי תוכנית
בנוסף למכסה היומית, כל מפתח API מוגבל למספר בקשות לדקה בהתאם לשכבת התוכנית שלו. זו מגבלת החלקה: היא מונעת מלקוח בודד לשלוח זינוק עצום בשנייה אחת, גם כשהתקציב היומי רחוק מלהיות מנוצל.
בנפרד, תקרות רחבות לכל IP ולכל חשבון חלות על כל ה־API כדי לשמור על יציבות הפלטפורמה. בשימוש רגיל — בקשות יציבות ומקוצבות — לעולם לא תיגעו בהן; הן מופעלות רק על התפרצויות פוגעניות.
- Free ו־Basic — 60 בקשות לדקה.
- Pro — 600 בקשות לדקה.
- Business — 1,800 בקשות לדקה.
- פזרו בקשות במקום לירות את כולן בבת אחת.
4קריאת התקציב הנותר שלכם
לעולם אינכם צריכים לנחש כמה מכסה נותרה. כל תגובה נמדדת — הצלחה או כישלון — כוללת שלוש כותרות: X-Quota-Limit (המגבלה היומית שלכם), X-Quota-Used (כמה קריאות ניצלתם היום), ו־X-Quota-Reset (הרגע, ב־UTC, שבו המונה מתאפס).
נקודות הקצה של בדיקת הספאם גם מהדהדות את אותם מספרים בתוך גוף התגובה תחת אובייקט quota, כך שתוכלו לקרוא את התקציב הנותר שלכם בלי לנתח כותרות. השתמשו בהם כדי לקצוב את הבקשות שלכם ולהזהיר את עצמכם לפני שתיגמר לכם.
- X-Quota-Limit — מגבלת הקריאות היומית שלכם.
- X-Quota-Used — קריאות שנוצלו עד כה היום.
- X-Quota-Reset — זמן איפוס ב־UTC (RFC 3339).
- תגובות בדיקת הספאם כוללות גם אובייקט quota עם אותם שדות.
5מה קורה ב־429
כשאתם חוצים אחת מהמגבלות, ה־API מחזיר HTTP 429 עם כותרת Retry-After שמציינת כמה שניות להמתין. עבור מגבלת הקצב לדקה, Retry-After הוא כדקה. עבור המכסה היומית, הגוף נושא קוד daily_quota_exceeded בתוספת התוכנית שלכם, המגבלה, ספירת השימוש, זמן האיפוס ורמז שדרוג, ו־Retry-After סופר לאחור עד חצות UTC.
הדרך הנכונה לטפל ב־429 היא להאט ולנסות שוב לאחר עיכוב ה־Retry-After, ולא להלום בנקודת הקצה. לקוחות מתנהגים היטב קוראים את הכותרת ומשהים; לקוחות שממשיכים לנסות מיד פשוט נשארים חסומים.
- 429 rate_limit_exceeded — שלחתם מהר מדי; המתינו כדקה.
- 429 daily_quota_exceeded — היום נוצל; המתינו עד איפוס ה־UTC או שדרגו.
- תמיד כבדו את כותרת Retry-After לפני ניסיון חוזר.