redditapis-mcp 0.10.1 → 0.10.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.10.2 (2026-10-14)
+
+### The 408 upstream_timeout read gets the same one retry
+
+The API now answers `408 {"error":"upstream_timeout"}` when a read did not complete in
+time (the body says it was not billed and names `retry_after`); before this release that
+case was a 500 and the model saw it as a failed tool call. A read answered that way is
+retried once after its `retry_after` (clamped 1..5 s), exactly like the 503
+`upstream_unavailable` retry from 0.10.1, and a 408 that is not retried carries a hint
+naming the retry. A 408 with any other error value, and a 408 on a write, are never
+retried.
+
 ## 0.10.1 (2026-10-14)
 
 ### One bounded retry on the API's transient 503, and a clearer 429

package/README.md

@@ -317,6 +317,8 @@ Reads need nothing but your API key -- no account linking, login, or cookie step
 
 **`HTTP 429 (rate limited)`** Wait a few seconds and retry, or reduce request frequency. For bulk work, space out calls and raise `REDDITAPIS_TIMEOUT_MS`.
 
+**`HTTP 408 (upstream_timeout)`** The read did not finish in time and was not billed. The server already retried once after `retry_after`; call the tool again shortly. A `503 upstream_unavailable` on a read gets the same one retry.
+
 **`Request failed: timed out after 30000ms`** The default timeout is 30 seconds. For large `reddit_deep_comment_search` or paginated fetches, set `REDDITAPIS_TIMEOUT_MS` higher (for example `60000`).
 
 **Tools do not appear in Claude / Cursor** Ensure `npx` is on your PATH and Node.js 18+ is installed (`node --version`). Check your MCP client logs for startup errors.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redditapis-mcp",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "mcpName": "io.github.redditapis/redditapis-mcp",
   "description": "Official MCP server for redditapis.com. Search Reddit posts, comments, communities, users and media; read subreddits, comment trees, top posts and profiles; create and manage monitors and webhooks. Native tools for Claude, Cursor and any MCP client.",
   "repository": {

package/src/server.js

@@ -134,6 +134,7 @@ export function hintFor(status, path) {
     for (const [re, hint] of NOT_FOUND_HINTS) if (re.test(path || "")) return hint;
     return DEFAULT_NOT_FOUND_HINT;
   }
+  if (status === 408) return " (the read did not complete in time; retry after the retry_after seconds)";
   if (status === 429) return " (slow down: wait the retry_after seconds, keep this key's reads in flight under the limit the message names, then retry)";
   if (status >= 500) return " (upstream API error. Retry in a moment; if persistent, contact https://www.redditapis.com)";
   return "";
@@ -279,8 +280,9 @@ export function createServer({
     // An API restart makes the gateway answer an HTML 502/503 or refuse the
     // connection for a short window. A READ is retried through it; timeouts and
     // writes never are, so a request the API may already have handled is never sent
-    // twice (a gateway 504 is not retried for that reason). The one API JSON error
-    // that IS retried is the read-side 503 upstream_unavailable below (0.10.1).
+    // twice (a gateway 504 is not retried for that reason). The API JSON errors
+    // that ARE retried, once, are the read-side 503 upstream_unavailable (0.10.1)
+    // and 408 upstream_timeout (0.10.2) below.
     // Only a REFUSED connection is retried: the request never reached the API,
     // so it cannot have been handled or billed. A reset, a broken pipe or a
     // socket dropped mid-answer can all happen after the API did the work, and
@@ -288,7 +290,9 @@ export function createServer({
     const RETRYABLE_NET = new Set(["ECONNREFUSED"]);
     const gatewayFailure = (status, text) =>
       (status === 502 || status === 503) && /^\s*<(!doctype|html)/i.test(text);
-    // The API's own transient refusal of a READ: 503 with error upstream_unavailable.
+    // The API's own transient refusal of a READ: 503 with error upstream_unavailable,
+    // and since 0.10.2 the 408 upstream_timeout it answers when a read did not
+    // complete in time (the body says it was not billed and names retry_after).
     // Its body says the call was not billed and names retry_after, so ONE retry after
     // that many seconds (clamped 1..5) never double-bills and turns a per-read refusal
     // into a slow success instead of a failed tool call (0.10.1). Never a write, never
@@ -296,8 +300,10 @@ export function createServer({
     // The TOP-LEVEL error value, parsed, never a substring match (review 2026-10-14:
     // a body nesting the string elsewhere must not be retried).
     const parsedBody = (text) => { try { const v = JSON.parse(text); return v && typeof v === "object" ? v : null; } catch { return null; } };
-    const apiTransientRead = (status, text) =>
-      status === 503 && parsedBody(text)?.error === "upstream_unavailable";
+    const apiTransientRead = (status, text) => {
+      const err = parsedBody(text)?.error;
+      return (status === 503 && err === "upstream_unavailable") || (status === 408 && err === "upstream_timeout");
+    };
     const retryAfterMs = (text) => {
       const s = Number(parsedBody(text)?.retry_after);
       return Math.min(5, Math.max(1, Number.isFinite(s) && s > 0 ? s : 2)) * 1000;