{"record":{"id":"21c6f363c48214d1","repo":"jackwener/OpenCLI","slug":"weread-official-apiname-returned-errcode-errc","errorCode":null,"errorMessage":"weread-official ${apiName} returned errcode=${errcode}","messagePattern":"weread-official (.+?) returned errcode=(.+?)","errorType":"exception","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/weread-official/utils.js","lineNumber":139,"sourceCode":"        const info = payload.upgrade_info;\n        const required = info?.required_version ?? info?.version ?? 'unknown';\n        const message = info?.message ?? 'WeRead skill version is outdated';\n        throw new CommandExecutionError(\n            `WeRead skill 需升级: ${message}. Required skill_version=${required}, current=${SKILL_VERSION}`,\n            'Pull the latest weread-skills.zip and bump SKILL_VERSION in clis/weread-official/utils.js.',\n        );\n    }\n\n    const errcode = Number(payload?.errcode ?? 0);\n    if (errcode !== 0) {\n        const errmsg = String(payload?.errmsg ?? 'unknown error');\n        if (AUTH_ERRCODES.has(errcode)) {\n            throw new AuthRequiredError(\n                WEREAD_DOMAIN,\n                `WEREAD_API_KEY rejected (errcode=${errcode}, ${errmsg}). Regenerate the key and re-export it.`,\n            );\n        }\n        throw new CommandExecutionError(\n            `weread-official ${apiName} returned errcode=${errcode}`,\n            errmsg,\n        );\n    }\n\n    return payload;\n}\n\n// ── Formatting helpers ──────────────────────────────────────────────────────\n\n/** Unix timestamp (sec) → YYYY-MM-DD using UTC for stable test snapshots. */\nexport function formatDate(ts) {\n    const seconds = Number(ts);\n    if (!Number.isFinite(seconds) || seconds <= 0) return '';\n    const date = new Date(seconds * 1000);\n    if (Number.isNaN(date.getTime())) return '';\n    const y = date.getUTCFullYear();\n    const m = String(date.getUTCMonth() + 1).padStart(2, '0');","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/weread-official/utils.js#L121-L157","documentation":"The gateway returned a non-zero errcode that is not an auth code. callGateway surfaces it as CommandExecutionError so the caller can react to the specific business error (bad parameter, no such resource, rate limit, permission, etc.).","triggerScenarios":"Any business-level rejection: invalid bookId, query syntax the API rejects, exceeding quota/rate limits, requesting a resource the account cannot access — whatever errmsg the gateway attached.","commonSituations":"Passing a bookId copied from a URL instead of from `weread-official search`; requesting highlights for a book not in the account; hammering the API and tripping errcode-based throttling.","solutions":["Read the errmsg detail for the exact business reason.","Correct the request parameters (validate bookId via requireBookId, non-empty query via requireText).","Back off and retry if the errcode indicates rate limiting.","Consult the WeRead gateway errcode table for this api_name."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// pre-validate inputs that commonly cause business errcodes\nif (!/^[A-Za-z0-9_-]+$/.test(bookId)) throw new Error(`Invalid bookId: ${bookId}`);\nif (!query || !query.trim()) throw new Error('Query cannot be empty');","typeGuard":"const isBusinessError = (e) => e instanceof CommandExecutionError && /errcode=\\d+/.test(e.message);","tryCatchPattern":"try {\n  return await callGateway(apiName, params);\n} catch (e) {\n  const m = /errcode=(\\d+)/.exec(e.message ?? '');\n  if (m) {\n    console.error(`Gateway business error ${m[1]}: ${e.detail ?? e.message}`);\n    if (['429','-1'].includes(m[1])) await sleep(5000); // throttle-style codes\n  }\n  throw e;\n}","preventionTips":["Always source bookIds from `weread-official search` output","Log errmsg/errcode pairs to a table for your api_names","Back off on rate-limit-style errcodes","Validate all business parameters with the require* helpers before calling"],"tags":["api-gateway","business-error","errcode"],"backgroundTag":"api-errcode-response","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}