From ffd2d937385c8df21b51f2bf450e6e571529f3ed Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sat, 11 Apr 2026 10:11:24 +0000 Subject: [PATCH] docs: document auto-learning, global rate cap, and transient error handling Generated-By: mintlify-agent --- api-reference/feedback.mdx | 11 +++++++++++ changelog.mdx | 16 ++++++++++++++++ errors.mdx | 19 +++++++++++++++---- rate-limits.mdx | 12 ++++++++++++ 4 files changed, 54 insertions(+), 4 deletions(-) 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. +