Account Health, Quota و Platform Rate Limits

1. مسئله: هر 403 یا 429 یک Retry ساده نیست

یک Worker ممکن است سه خطای ظاهراً شبیه ببیند: GitHub-like rate limit، YouTube quotaExceeded و یک authorization failure. اگر هر سه را «retryable» بداند، می‌تواند quota را بیشتر بسوزاند، throttling را تشدید کند یا خطای دسترسی را پنهان کند. خروجی این درس Account Health & Quota Guardrail Ledger v1 است.

2. مرز درس

PLN-024 فقط Account/Auth/Permission/Restriction و Quota/Rate-limit evidence را به action محدود تبدیل می‌کند. تراکنش Publish درس PLN-023 و Persona Model درس PLN-025 خارج از Scope هستند. هیچ API واقعی فراخوانی نمی‌شود و هیچ Credential واقعی لازم نیست.

3. FACT خارجی و MAKNOW DESIGN

GitHub REST API در مستند فعلی Primary و Secondary rate limit را جدا می‌کند، status headerهای Primary limit را برمی‌گرداند و برای rate-limit می‌تواند 403 یا 429 بدهد. YouTube Data API نیز quotaExceeded را به‌عنوان quota error جدا ثبت می‌کند و در 2026 granular quota bucket را برای بعضی methodها شروع کرده است. اما taxonomy سلامت و actionهای این Ledger، MAKNOW DESIGN هستند.

4. Account Identity را قبل از Error Class ببند

با account_id و platform_id شروع کن. یک header یا status بدون اینکه بدانیم مربوط به کدام account/project/integration است قابل تصمیم‌گیری نیست. Evidence باید به همان هویت محدود باشد؛ signal یک account را به account دیگر تعمیم نده.

5. Auth، Permission و Restriction سه چیز متفاوت‌اند

auth_state می‌گوید Credential معتبر است یا نه. permission_state می‌گوید principal مجاز به operation هست یا نه. account_restriction_state محدودیت policy/account-level را نگه می‌دارد. Auth منقضی → REAUTH_REQUIRED. Permission یا policy block را نباید quota exhaustion نامید.

6. Quota Model باید Provider-specific باشد

quota_model و quota_bucket دقیقاً نشان می‌دهند limit کجا اعمال می‌شود: global، resource-specific، method-specific یا secondary throttle. یک مدل جهانی برای همه Providerها نساز. اگر Provider bucket را عوض کند، نتیجه قبلی باید invalid شود.

7. Operation و Cost را همراه Bucket ثبت کن

method_or_operation و quota_cost باید در همان Evidence row باشند. در YouTube امروز search.list و videos.insert bucketهای granular خودشان را دارند؛ همین مثال نشان می‌دهد cost/bucket می‌تواند با revisionهای Provider عوض شود. Cost قدیمی را بدون Freshness check استفاده نکن.

8. Remaining، Reset و Retry-After نقش‌های متفاوت دارند

remaining_value ظرفیت باقی‌مانده را نشان می‌دهد؛ reset_at زمان reset یک window را؛ retry_after delay صریح Provider را. GitHub برای primary exhaustion به reset و برای secondary limit در صورت وجود به Retry-After اشاره می‌کند. از این signalها action می‌سازیم، نه از یک backoff ثابت جهانی.

9. HTTP Status به‌تنهایی Oracle نیست

403 می‌تواند rate limit، authorization یا policy مشکل باشد. 429 هم context و recovery signal می‌خواهد. بنابراین http_status باید کنار provider_error_code، auth/permission state و rate-limit class دیده شود. اگر classification مبهم است، AMBIGUOUS یا BLOCKED بهتر از retry خوش‌بینانه است.

10. Freshness و Provenance بخشی از Health هستند

evidence_retrieved_at و provenance_ref تزئینی نیستند. Quota value، method cost و provider policy می‌توانند عوض شوند. Evidence قدیمی یا بی‌منبع اجازه ALLOW ندارد؛ اول باید refresh شود.

11. Health State و Allowed Action را جدا نگه دار

health_state توصیف وضعیت evidence است؛ allowed_action رفتار بعدی را محدود می‌کند. نمونه‌ها: HEALTHY → ALLOW، RATE_LIMITED → DEFER_UNTIL_RESET، AUTH_REQUIRED → REAUTH_REQUIRED، PERMISSION_BLOCKED → POLICY_REVIEW، QUOTA_EXHAUSTED → QUOTA_REVIEW و evidence ناقص → BLOCKED.

12. Baseline — سه Failure با سه مسیر متفاوت

در fixture، GitHub-like primary limit با remaining صفر تا reset باید defer شود؛ YouTube quotaExceeded باید وارد quota review شود؛ credential منقضی باید reauth شود. یک worker که هر سه را exponential retry کند، boundary درس را شکسته است.

13. Shortcutهای خطرناک

1. 403 را همیشه quota بدانی. ۲) قبل از Retry-After یا reset دوباره request بدهی. ۳) remaining/reset قدیمی را معتبر فرض کنی. ۴) authorization failure را با خرید quota حل کنی. ۵) بعد از granular شدن یک method، هنوز global bucket قبلی را Oracle بگیری.

14. Transfer — Operation وارد Bucket جدا شده است

در Transfer، operation search.list دیگر از bucket global قبلی مصرف نمی‌کند. Ledger باید quota_bucket، quota_cost، remaining_value و recheck_at را از evidence جدید دوباره بسازد. نتیجه baseline قابل کپی نیست: ممکن است global pool exhausted باشد ولی method-specific bucket هنوز اجازه ALLOW بدهد.

15. Lab، Assessment و Freshness

در lab/PLN-024-LAB1/learner/ دستور python run_checks.py را اجرا کن. هشت Fixture مسیرهای ALLOW، DEFER، REAUTH، POLICY_REVIEW، QUOTA_REVIEW، STALE، UNKNOWN و Transfer را پوشش می‌دهند. منابع GitHub و YouTube در 2026-09-16 دوباره بررسی شده‌اند؛ هر تغییر در package قفل‌شده نیازمند version جدید است.