Document auto-learning, global rate cap, and transient errors

api-reference/feedback.mdx

@@ -15,6 +15,17 @@ Submit reinforcement learning from human feedback (RLHF) to continuously improve
   Every feedback submission helps improve accuracy for all NAWA users. We especially value feedback on dialect detection edge cases.
 </Tip>
 
+## How NAWA learns
+
+NAWA's learning pipeline combines two signal sources:
+
+1. **Explicit feedback** -- you submit corrections via this endpoint. These are high-value signals because a human has verified the correct answer.
+2. **Implicit auto-process signals** -- when NAWA successfully auto-processes a comment (reply or heart), a positive learning signal is recorded automatically. Skip decisions are excluded because they are not positive learning events for the reply generator.
+
+Both signals feed into the same `ai_learning_patterns` store. Over time, NAWA's `PatternLearner` reads these patterns to recommend better classification and reply approaches for your content.
+
+You do not need to change your integration to benefit from implicit signals. They are recorded automatically on every successful auto-process.
+
 ## Request
 
 ### Body parameters

changelog.mdx

@@ -4,6 +4,22 @@ description: "NAWA API platform updates and releases"
 rss: true
 ---
 
+<Update label="April 11, 2026" description="v1.2.1" tags={["API", "Reliability", "Learning"]}>
+## Adaptive learning, global rate cap, and transient error handling
+
+### Adaptive learning pipeline activated
+NAWA now records implicit positive learning signals when comments are successfully auto-processed (reply or heart decisions). These signals feed into the same `ai_learning_patterns` store that explicit `/v1/feedback` submissions use, so classification and reply quality improve automatically over time. Skip decisions are excluded. No API changes required -- this works transparently for all users.
+
+### Global platform rate cap
+A global sliding-window rate limiter (900 RPM across all users) now protects against upstream provider limits. If the global cap is reached, you receive a standard `429` response with a `Retry-After` header. Per-key limits are unchanged. See [rate limits](/rate-limits#global-platform-rate-limit) for details.
+
+### Transient error differentiation
+Rate limits (429), service unavailable (503), network timeouts, and connection resets are now classified as transient errors with `retry_pending` status instead of permanent `failed`. NAWA auto-retries transient errors so you no longer need to manually reprocess comments that failed due to brief upstream hiccups. See [errors](/errors#transient-vs-permanent-errors) for the full taxonomy.
+
+### Sync failure visibility
+YouTube sync jobs that encounter errors (including token expiry) now properly report failure status instead of silently stalling. The dashboard surfaces a reconnect prompt when your YouTube connection expires mid-sync.
+</Update>
+
 <Update label="April 8, 2026" description="v1.2.0" tags={["API", "New Endpoint", "English"]}>
 ## Intelligence Report API + English support
 

errors.mdx

@@ -198,13 +198,13 @@ Your account balance is insufficient for the requested operation.
 
 ### `rate_limit_error` (429)
 
-You've exceeded the rate limit for your current tier.
+You've exceeded the rate limit for your current tier, or the platform-wide global cap has been reached.
 
 <AccordionGroup>
   <Accordion title="rate_limit_exceeded">
-    **Cause:** Too many requests in the current time window.
+    **Cause:** Too many requests in the current time window. This can be triggered by your per-key limit or by the global platform cap.
 
-    **Fix:** Wait until the `X-RateLimit-Reset` time, then retry. Consider upgrading your tier.
+    **Fix:** Wait until the `X-RateLimit-Reset` time, then retry. Consider upgrading your tier for higher per-key limits.
 
     ```json
     {
@@ -215,7 +215,7 @@ You've exceeded the rate limit for your current tier.
     }
     ```
 
-    The `X-NAWA-RateLimit-Reason` response header provides additional context (`minute_limit` or `sandbox_exhausted`).
+    The `X-NAWA-RateLimit-Reason` response header provides additional context (`minute_limit`, `global_cap`, or `sandbox_exhausted`).
   </Accordion>
 
   <Accordion title="sandbox_exhausted">
@@ -234,6 +234,17 @@ You've exceeded the rate limit for your current tier.
   </Accordion>
 </AccordionGroup>
 
+### Transient vs permanent errors
+
+NAWA classifies upstream errors into two categories:
+
+| Category | Behavior | Examples |
+|----------|----------|---------|
+| **Transient** | Auto-retried by NAWA. Status: `retry_pending`. | 429 rate limit, 503 service unavailable, network timeouts, connection resets |
+| **Permanent** | Requires your intervention. Status: `failed`. | 400 bad request, 401 authentication, 500 internal server error |
+
+When you retrieve comments or processing results through the dashboard or API, the `processing_status` field reflects this distinction. Transient errors resolve automatically within seconds as NAWA retries the request. Permanent errors need attention -- check the `error_message` field for details.
+
 ### `api_error` (500)
 
 An unexpected error occurred on the NAWA side.

rate-limits.mdx

@@ -97,3 +97,15 @@ def classify_with_retry(nawa: Nawa, text: str, platform: str, max_retries: int =
 <Warning>
   Do not retry in a tight loop without backoff. This will extend your rate limit window and may result in longer delays.
 </Warning>
+
+## Global platform rate limit
+
+In addition to per-key limits, NAWA enforces a global request cap across all users to stay within upstream AI provider limits. This cap uses a 60-second sliding window.
+
+- The global cap is set conservatively below the upstream provider ceiling (currently 900 requests per minute platform-wide).
+- If the global cap is reached, your request returns a `429` with a `Retry-After` header, even if your per-key limit has not been exceeded.
+- Global cap hits are rare under normal load. If you see them consistently, contact [sales@trynawa.com](mailto:sales@trynawa.com) to discuss capacity.
+
+<Note>
+  Semantic cache hits bypass the global cap entirely. High cache hit rates protect you from both per-key and global limits.
+</Note>