diff --git a/api-reference/feedback.mdx b/api-reference/feedback.mdx
index 4cddf8b..b348f57 100644
--- a/api-reference/feedback.mdx
+++ b/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.
+## 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
diff --git a/changelog.mdx b/changelog.mdx
index 43e9d75..cc1c51b 100644
--- a/changelog.mdx
+++ b/changelog.mdx
@@ -4,6 +4,22 @@ description: "NAWA API platform updates and releases"
rss: true
---
+
+## 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.
+
+
## Intelligence Report API + English support
diff --git a/errors.mdx b/errors.mdx
index fdcf365..985c263 100644
--- a/errors.mdx
+++ b/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.
- **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`).
@@ -234,6 +234,17 @@ You've exceeded the rate limit for your current tier.
+### 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.
diff --git a/rate-limits.mdx b/rate-limits.mdx
index 26c3d15..ff6ce92 100644
--- a/rate-limits.mdx
+++ b/rate-limits.mdx
@@ -97,3 +97,15 @@ def classify_with_retry(nawa: Nawa, text: str, platform: str, max_retries: int =
Do not retry in a tight loop without backoff. This will extend your rate limit window and may result in longer delays.
+
+## 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.
+
+
+ Semantic cache hits bypass the global cap entirely. High cache hit rates protect you from both per-key and global limits.
+