Account Health, Quota and Platform Rate Limits

1. Problem: every 403 or 429 is not one retryable failure

A worker can observe three superficially similar failures: a GitHub-like rate limit, a YouTube quotaExceeded error, and an authorization failure. Treating all three as retryable can burn more quota, amplify throttling, or hide an access problem. This lesson produces Account Health & Quota Guardrail Ledger v1.

2. Lesson boundary

PLN-024 owns account/auth/permission/restriction and quota/rate-limit evidence translated into a bounded next action. PLN-023 publish transactions and PLN-025 persona modeling stay out of scope. No live provider request is made and no production credential is required.

3. External FACT versus MAKNOW DESIGN

Current GitHub REST documentation distinguishes primary and secondary rate limits, exposes primary-limit headers, and can return 403 or 429 for rate limiting. YouTube Data API documents quotaExceeded separately and began moving selected methods to granular quota buckets in 2026. The health taxonomy, precedence, and allowed-action states in this ledger are MAKNOW DESIGN.

4. Close account identity before classifying the error

Start with account_id and platform_id. A status code or header without the account/project/integration identity is not enough for a decision. Evidence must stay scoped to the identity that produced it; never transfer a quota signal from one account to another.

5. Auth, permission, and restriction are separate dimensions

auth_state describes whether credentials are usable. permission_state describes whether the principal may perform the operation. account_restriction_state holds policy or account-level restrictions. Expired auth yields REAUTH_REQUIRED; permission or policy denial must not be relabeled as quota exhaustion.

6. Quota models are provider-specific

quota_model and quota_bucket state where a limit applies: global, resource-specific, method-specific, or secondary throttling. Do not invent one cross-provider quota model. When a provider changes bucket boundaries, the previous conclusion must be recomputed.

7. Bind operation and cost to the bucket

method_or_operation and quota_cost belong in the same evidence row as the bucket. YouTube currently gives search.list and videos.insert their own granular buckets; this is a concrete example of provider revision changing quota accounting. Old method cost is not current evidence without a freshness check.

8. Remaining, reset, and Retry-After are different signals

remaining_value describes remaining budget, reset_at identifies a window reset, and retry_after is an explicit delay signal. GitHub directs primary-limit recovery to reset information and secondary-limit recovery to Retry-After when present. The guardrail derives action from these signals instead of a universal fixed backoff.

9. HTTP status alone is not an oracle

A 403 can represent rate limiting, authorization, or policy restrictions. A 429 also needs context and recovery evidence. Therefore http_status must be read together with provider_error_code, auth/permission state, and rate-limit class. Ambiguous classification should remain AMBIGUOUS or BLOCKED, not optimistic retry.

10. Freshness and provenance are part of health

evidence_retrieved_at and provenance_ref are operational fields. Quota values, method costs, and provider policy can change. Stale or untraceable decisive evidence cannot produce ALLOW; refresh it first.

11. Keep health state separate from allowed action

health_state describes evidence; allowed_action constrains behavior. Examples include HEALTHY → ALLOW, RATE_LIMITED → DEFER_UNTIL_RESET, AUTH_REQUIRED → REAUTH_REQUIRED, PERMISSION_BLOCKED → POLICY_REVIEW, QUOTA_EXHAUSTED → QUOTA_REVIEW, and incomplete evidence → BLOCKED.

12. Baseline — three failures, three routes

The fixture includes a GitHub-like primary limit with zero remaining until reset, a YouTube quotaExceeded, and an expired credential. They must route to defer, quota review, and reauthentication respectively. A worker that applies the same exponential retry to all three has collapsed the lesson boundary.

13. Dangerous shortcuts

Do not: classify every 403 as quota; retry before Retry-After/reset permits; reuse stale remaining/reset values; solve authorization failure by adding quota; or keep the old global bucket after a provider introduces a method-specific bucket.

14. Transfer — one operation moves to a separate bucket

In the transfer case, search.list no longer consumes the old global pool. The ledger must recompute quota_bucket, quota_cost, remaining_value, and recheck_at from new evidence. The baseline conclusion cannot be copied: a depleted global pool can coexist with a healthy method-specific bucket.

15. Lab, assessment, and freshness

Run python run_checks.py under lab/PLN-024-LAB1/learner/. Eight fixtures cover ALLOW, DEFER, REAUTH, POLICY_REVIEW, QUOTA_REVIEW, STALE, UNKNOWN, and transfer. GitHub and YouTube sources were rechecked on 2026-09-16. Any change to locked package bytes requires a new version.