📘 תיעוד 74

מגבלות הוצאה של Claude apps gateway

הגבלת ההוצאה של כל מפתח דרך Claude apps gateway לפי יום, שבוע או חודש. הגדרת מגבלות מתבצעת באמצעות Admin API, והשער אוכף אותן בזמן אמת בכל בקשה.

מגבלות הוצאה מגבילות את הסכום שכל מפתח יכול להוציא דרך Claude apps gateway ביום, שבוע או חודש מסוימים. כאשר מפתח עובר את התקרה שלו, השער מחזיר שגיאת 429 בבקשה הבאה שלו וחוסם אותו עד שהתקופה מתאפסת או שמנהל מערכת מעלה את התקרה. השתמש במגבלות הוצאה כדי לקבוע לכל מפתח, קבוצה או לארגון כולו תקרה על גבי פרטי הזיהוי המשותפים לכולם.

שער Claude apps gateway מעביר את כל תעבורת ההיסק דרך פרטי זיהוי משותפים יחידים מול הספק במעלה הזרם, ולכן חשבון הספק שלך מייחס את כל העלויות לפרטי זיהוי אלה, ולא למפתחים יחידים. ללא מגבלות לכל מפתח, צי סוכנים בודד שיצא משליטה עלול לכלות את כל מסגרת ההתחייבות של הארגון. מגבלות הוצאה הן תצוגה ברמת המפתח ומפסק מגן של השער על גבי אותו חשבון משותף.

#הגדרת מגבלה

כאשר הבלוק admin: מוגדר בתוך gateway.yaml, השער מפעיל Admin API בנתיב /v1/organizations/spend_limits ואוכף תקרות בזמן אמת בכל בקשת היסק. התקרות עצמן מוגדרות דרך ה-API הזה, ולא בתוך gateway.yaml: כל בקשת POST /v1/organizations/spend_limits יוצרת או מחליפה תקרה אחת מתוך {scope, amount, period}. ה-API תואם למבנה הנתונים של נקודות הקצה של מגבלות ההוצאה ב-Admin API הציבורי של Anthropic, כך שלקוח HTTP שנכתב מול הממשק הזה יכול לפנות לשער פשוט על ידי שינוי כתובת הבסיס שלו.

בקשה זו מגדירה ברירת מחדל כלל ארגונית של 500 דולר לחודש לכל מפתח:

curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \
  -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": {"type": "organization"}, "amount": "50000", "period": "monthly"}'

בקשה זו מוסיפה שכבה של תקרה הדוקה יותר של 100 דולר ליום לכל חבר בקבוצת contractors:

curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \
  -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": {"type": "rbac_group", "rbac_group_id": "contractors"}, "amount": "10000", "period": "daily"}'

תקרה של קבוצה או של ארגון היא ברירת מחדל לכל מושב שכל חבר בה יורש, ולא תקציב משותף. לכל תקופה, התקרה האפקטיבית של מפתח נקבעת לפי הסדר הבא: דריסה ספציפית למשתמש, לאחר מכן התקרה המחמירה ביותר מבין הקבוצות שלו, לאחר מכן ברירת המחדל של הארגון, ולבסוף ללא הגבלה. ההגדרה admin.group_limit_mode: max הופכת את הכרעת השוויון בריבוי קבוצות כך שתבחר דווקא את התקרה הפחות מחמירה.

#אימות מול ה-Admin API

שלח אחד מאלה:

• כותרת x-api-key התואמת למפתח מתוך admin.write_keys לגישה מלאה, או מתוך admin.read_keys לגישת GET בלבד. כל מפתח נושא id שמופיע ביומן הביקורת בתור admin-key:<id>, לכן מומלץ להקצות מפתח ייעודי ל-Terraform, ל-CI ולכל תהליך אוטומציה.
• אסימון bearer של השער שטענת ה-groups שלו כוללת אחת מהקבוצות ב-admin.admin_groups. זוהי גישה מלאה שנרשמת בביקורת בתור oidc:<sub>, ולכן עדיף להשתמש בה עבור מנהלי מערכת אנושיים.

#כיצד פועלת האכיפה

בכל בקשת /v1/messages, השער בודק את התקרות של המפתח ואת סך ההוצאה המצטברת לתקופה בשאילתת Postgres אחת. מפתח שנמצא מעל תקרה כלשהי מקבל תשובת 429 עם error.type: billing_error והכותרת x-should-retry: false.

ההודעה מציינת את התקופה ואת מועד האיפוס, לדוגמה spend limit reached (daily; resets 2026-08-08 00:00 UTC), ולאחריה את הערך של admin.blocked_message אם הוגדר. כאשר מפתח חורג מכמה תקרות בו זמנית, ההודעה מציינת את התקרה שמתאפסת אחרונה. התגובה כוללת גם כותרת retry-after עם מספר השניות שנותרו עד לאותו איפוס. לפני גרסה v2.1.225 בשרת השער, ההודעה הייתה spend limit reached ללא ציון תקופה, מועד איפוס או כותרת retry-after.

בגרסה v2.1.227 ואילך, מסמך הפרוטוקול בכתובת <public_url>/protocol מציג גם את כותרות התגובה המדויקות של מגבלת השימוש ואת מבנה גוף שגיאת ה-429.

התקרות מתאפסות לפי גבולות לוח השנה ב-UTC: יומי ב-00:00 UTC, שבועי ביום שני, וחודשי ביום הראשון לחודש. השער לעולם אינו חוסם את /v1/messages/count_tokens, מכיוון שספירת טוקנים אינה כרוכה בתשלום.

#כיצד מחושב התמחור של בקשות

לאחר כל תגובה, מד שימוש קורא את כמויות הטוקנים ומוסיף את העלות למונים היומיים, השבועיים והחודשיים. המד לעולם אינו נוגע בבתים הנשלחים ללקוח, כך שכשל במדידה אינו יכול לפגוע בתגובה. הסכומים הם הערכות ב-USD ומשמשים כמפסק מגן ולא כחשבונית: לצורך חיוב כספי, יש לבצע התאמה מול דיווחי השימוש של הספק שלך.

המד בוחר את התעריפים של כל בקשה לפי הסדר הבא:

1. שורת pricing.overrides תואמת עבור שירות ה-upstream שטיפל בבקשה. דורש גרסה v2.1.227 ואילך.
2. מחיר מחירון עבור מזהה הדגם ב-upstream, המחרוזת שהשער שולח לספק, כאשר טבלת העלויות של Claude Code מזהה אותו. הטבלה תומכת במבני מזהים של Anthropic, Amazon Bedrock, Google Cloud's Agent Platform ו-Microsoft Foundry.
3. מחיר מחירון עבור ה-models[].id שמיפית לאותו מזהה upstream, עבור מחרוזות upstream שאינן מכילות שם דגם, כגון ARN של פרופיל היסק יישומים ב-Amazon Bedrock או שם פריסה ב-Microsoft Foundry. דורש גרסה v2.1.218 ואילך.
4. מדרגת דגם לא ידוע בתעריף של 5 דולר לקלט ו-25 דולר לפלט למיליון טוקנים, כדי שמזהה שהמד אינו מזהה לעולם לא יהיה בחינם. השער מציג אזהרה בעת העלייה ופעם אחת לכל מזהה בזמן ריצה כאשר נעשה שימוש במדרגה זו.

ללא תלות בתעריף שנבחר, המד מכפיל את הסכום בערך של pricing.multiplier, שברירת המחדל שלו היא 1.

גם ביטולים יזומים של הלקוח מחוייבים. כאשר זרם נתקע או מסתיים ללא מסגרת השימוש הסופית של ה-upstream, המד מחייב לפי הערכת מינימום של כארבעה תווים לכל טוקן פלט עבור הטקסט שכבר נשלח ללקוח, כדי שביטול מוקדם של בקשות לא ישמש לעקיפת התקרה.

#זמינות של Postgres

הבדיקה המקדימה שולחת שאילתה ל-Postgres עם מגבלת זמן של שתי שניות. אם מסד הנתונים אינו זמין או שהזמן תם, האכיפה פועלת כברירת מחדל במצב פתוח: הבקשה ממשיכה כרגיל, השער מתעד אזהרה ביומן, והתגובה אינה כוללת כותרות anthropic-ratelimit-unified-*. הגדרת enforcement.fail_closed_on_error: true משנה את ההתנהגות למצב סגור במקרה של שגיאה, מה שמחזיר את אותה שגיאת 429 billing_error אך עם ההודעה spend limit unavailable וללא פירוט תקופה, מועד איפוס או כותרת retry-after. מצב כשל פתוח מונע מתקלה במסד הנתונים להשבית את שירות ההיסק, בעוד מצב כשל סגור מבטיח שלא תהיה הוצאה לא מנוטרת.

#אזהרות שימוש ב-Claude Code

הכלי Claude Code מזהיר מפתח כאשר הוא מתקרב לתקרה שלו: פעם ראשונה כאשר הניצול חוצה 75%, ופעם נוספת לאחר 95% מהתקרה שנוצלה במידה הרבה ביותר. כאשר השער חוסם בקשה, Claude Code מציג את הודעת ה-429 של השער כפי שהיא, כולל ההודעה המותאמת אישית מתוך admin.blocked_message.

האזהרה פועלת על בסיס כותרות תגובה:

• עם גרסה v2.1.225 ואילך בשרת השער, כל תגובת /v1/messages מוצלחת עבור מפתח שיש לו תקרה נושאת את שיעור ניצול התקרה שלו ואת מועד האיפוס בכותרות anthropic-ratelimit-unified-*.
• עם גרסה v2.1.225 ואילך גם במחשב של המפתח, Claude Code קורא את הכותרות ומציג את האזהרה.

הכותרות תמיד מתארות את התקרה האישית של המפתח: השער מסיר את כותרות מגבלת הקצב של ספק ה-upstream, המתארות את המכסה המשותפת של הארגון, ולעולם אינו מעביר אותן הלאה.

עם גרסה v2.1.251 ואילך במחשב של המפתח, Claude Code קורא את אותן כותרות כדי להציג מד Spend limit בפקודה /usage, עם אחוז הניצול מהתקרה ומועד האיפוס שלה, ומוסיף אובייקט rate_limits.spend_limit לנתוני שורת המצב. Claude Code מציג את שניהם כאחוז ולא כסכום דולרי, ואינו דורש גרסה חדשה יותר מ-v2.1.225 בשרת השער.

#תיעוד ה-Admin API

נקודות הקצה שלהלן מוגשות תחת הנתיב /v1/organizations/spend_limits.

המוסכמות תואמות את ה-Admin API של Anthropic:

• שדה type בכל אובייקט
• מזהים בעלי קידומת spl_
• סכומים כמחרוזות מספרים שלמים של סנטים ב-USD: בקשת POST דוחה כל ערך currency אחר עם שגיאת 400
• מעטפת שגיאה אחידה במבנה {type: "error", error: {type, message}, request_id}
• כותרת תגובה request-id בכל תגובה של ה-admin, בהצלחה או בשגיאה: גוף השגיאה כולל מזהה זה גם תחת request_id

כל שינוי רושם שורת לפני ואחרי בטבלה admin_audit באותה טרנזקציה, המיוחסת ל-admin-key:<id> או ל-oidc:<sub>.

השער מספק את נקודות הקצה של מגבלות ההוצאה בלבד. ממשקי Admin API אחרים, כגון התור spend_limit_increase_requests, אינם חלק מה-API של השער.

#/effective

הנתיב GET /v1/organizations/spend_limits/effective מחזיר נתונים לפי סכמת SpendSummary של Anthropic: כל שורה מייצגת ישות עבור תקופה מסוימת, יחד עם התקרה שנקבעה, ההוצאה המצטברת לתקופה ואובייקט actor. הבדלים הייחודיים לשער:

• השדה user_id הוא ה-sub מתוך OIDC.
• השדות actor.name ו-actor.email_address מכילים null עד לבקשת ההיסק הראשונה של אותה ישות דרך השער. לשער אין ספריית משתמשים: הוא שומר ערכים שנצפו לאחרונה מתוך ה-JWT של הפעלת המשתמש עצמו.
• כל שורה כוללת גם מערך groups עם קבוצות ה-IdP שנצפו לאחרונה עבור הישות. זוהי הרחבה של השער שנועדה לאפשר לממשק ניהול להציג כל דרגת תקרה שחלה: לקוחות הפועלים לפי המבנה המקורי של Anthropic מתעלמים ממנה.
• ללא מסנן user_ids[], הנתיב מציג רק ישויות עם הוצאה מתועדת, מכיוון שהשער אינו יכול למנות את כלל חברי הארגון.

תקרות שמקורן בקבוצה נקבעות מול אותן קבוצות שנצפו לאחרונה תוך שימוש באותו מנגנון הכרעת שוויון של group_limit_mode המשמש באכיפה, כך שהתצוגה משקפת את התקרה שחלה בפועל.

אזהרה: הפרמטרים q= ו-user_ids[]= מועברים במחרוזת השאילתה של בקשת GET, ולכן כל פרוקסי או מאזן עומסים בחזית לוכד אותם ביומני הגישה שלו. אם מדיניות הפרטיות וה-PII בארגון מחמירה, יש לנקות פרמטרים אלה שם.

#/audit

מחזיר את יומן השינויים של מגבלות ההוצאה: מי שינה איזו תקרה, עם תמונת מצב של לפני ואחרי, מהחדש לישן. השדה has_more מדויק. נקודת קצה זו פועלת לפי מוסכמות ה-Admin API המקומיות ולא לפי מבנה נתונים חיצוני.

#עימוד

הרשימה הגולמית מדפדפת באמצעות after_id ו-before_id, שהם מזהי spl_... המוציאים זה את זה: התוצאות ממוינות לפי מועד היצירה והשדה has_more משקף את כיוון הדפדוף. הנתיב /effective מדפדף באמצעות אסימון next_page המועבר חזרה בתור ?page=, כאשר הישויות ממוינות בסדר עולה כדי שהעמודים יישארו יציבים בזמן שנרשמת הוצאה שוטפת. הפרמטר limit נקבע בין 1 ל-1000 בשניהם, עם ברירת מחדל של 20. הנתיב /audit מדפדף לפי after_id, שהוא המזהה המספרי של האירוע האחרון בעמוד הקודם, וברירת המחדל של limit בו היא 100.

#מחזור חיי הנתונים

השער מנהל ארבע טבלאות הקשורות להוצאות: סריקה שעתית אוכפת את חלונות שמירת הנתונים:

כאשר מפתח עוזב, מחק כל תקרה המוגדרת עבורו באמצעות DELETE /v1/organizations/spend_limits/{id}: נתוני ההוצאה והזהות שלו יימחקו בהתאם לחלונות השמירה המפורטים למעלה. כדי למחוק אדם בודד באופן מיידי, לצורך תהליך עזיבה או מענה לבקשת גישה של נושא מידע (DSAR), הרץ פקודת DELETE FROM principal_emails WHERE principal = '<sub>' ישירות מול מסד הנתונים של השער. פקודה זו מוחקת את הטבלה היחידה שמחזיקה את כתובת האימייל, השם והקבוצות שלו. הרשומות בטבלאות spend ו-admin_audit מקושרות למזהה הפסאודונימי sub של OIDC בלבד ונמחקות מעצמן בתום חלון השמירה שלהן.

#נושאים קשורים

• הגדרות admin ו-enforcement: הפעלת ה-Admin API והתאמת תקופות שמירת נתונים
• מדריך פריסה: סכמת Postgres והנחיות לגיבוי