📘 תיעוד 112

מגבלות הוצאה בשער יישומי Claude

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

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

כברירת מחדל, שער יישומי Claude מעביר את כל ההסקה דרך credential אחד משותף ב-upstream, כך שחשבון הספק שלך מייחס הכל ל-credential הזה, ולא למפתחים בודדים. ב-Amazon Bedrock, ייחוס עלות AWS לפי מפתח משנה את זה. בלי מגבלות לפי מפתח, צי סוכנים אחד שיצא משליטה יכול להוציא את כל ההתחייבות של הארגון. מגבלות הוצאה הן המבט לפי מפתח של השער, ומפסק הזרם שמעליו על החשבון המשותף הזה.

#הגדרת תקרה

כשבלוק admin: מוגדר ב-gateway.yaml, השער מגיש Admin API בנתיב /v1/organizations/spend_limits ואוכף תקרות בזמן אמת על כל בקשת הסקה. התקרות עצמן נקבעות דרך ה-API הזה, ולא ב-gateway.yaml. כל בקשת POST /v1/organizations/spend_limits יוצרת או מחליפה תקרה אחת מתוך {scope, amount, period}. ה-API משקף את צורות ה-wire של נקודות הקצה של מגבלות הוצאה ב-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 של השער ש-claim בשם 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, כי ספירת אסימונים היא בחינם.

#איך בקשות מתומחרות

אחרי כל תשובה, מד שימוש קורא את ספירות האסימונים ומוסיף את העלות למונים היומי, השבועי והחודשי. הוא אף פעם לא נוגע בבתים שנשלחים ללקוח, כך שכשל במדידה לא יכול לשבור תשובה. הסכומים הם אומדנים בדולר ארה"ב, מפסק זרם ולא חשבונית. לחיוב, התאם מול דיווח השימוש של הספק שלך.

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

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

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

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

#תעריפי פרומפט ארוך

למחירון של Claude Haiku 5.5 יש תעריף גבוה יותר לפרומפטים מעל סף אסימונים. כש-Haiku 5.5 משרת בקשה שהפרומפט שלה עובר את הסף, שרת שער שרץ על Claude Code v2.1.293 ואילך מתמחר את כל הבקשה בתעריף הזה. המד סופר אסימוני קלט, קריאות מטמון וכתיבות מטמון לקראת הסף הזה.

אם אחת משורות pricing.overrides שלך תואמת את הבקשה, התעריפים של השורה הזו חלים בכל אורך פרומפט.

#זמינות Postgres

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

כשל פתוח עוזר רק כל עוד מאזן העומס או המתזמר שלך עדיין מנתב תעבורה לשער. ראה התנהגות בתקלה עבור store.readiness_grace_seconds, ששומר על עותקים שעוברים את בדיקת המוכנות שלהם במהלך תקלה קצרה.

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

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

כל תצוגה דורשת גרסת Claude Code מינימלית במכונה של המפתח ובשרת השער:

האזהרות והאחוז מגיעים מכותרות anthropic-ratelimit-unified-*, שהשער מוסיף לכל תשובת /v1/messages מוצלחת עבור מפתח שיש לו תקרה. הכותרות תמיד מתארות את התקרה של המפתח עצמו: השער מסיר את כותרות מגבלת הקצב של ספק ה-upstream, שמתארות את המכסה המשותפת שלך, ואף פעם לא מעביר אותן הלאה.

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

#הפניה ל-Admin API

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

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

• type על כל אובייקט
• מזהים עם קידומת spl_
• סכומים כמחרוזות מספר שלם של סנטים בדולר ארה"ב. 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, אינם חלק מ-Admin API של השער.

#/effective

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

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

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

[!WARNING]

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

#/audit

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

#עימוד

הרשימה הגולמית מתעייפת לפי after_id ו-before_id, שהם מזהי spl_… שמוציאים זה את זה. התוצאות מסודרות לפי יצירה, ו-has_more משקף את כיוון המעבר. /effective מתעייף לפי אסימון next_page האטום שמוחזר כ-?page=, עם principals מסודרים בסדר עולה כדי שהעמודים יישארו יציבים בזמן שההוצאה נרשמת. limit הוא 1-1000, ברירת מחדל 20, בשניהם. /audit מתעייף לפי after_id, ה-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 והנחיות גיבוי