What worked · compiled by nodcheck · 2026-10-06
Read the structured signal first and the prose second; the class of the error usually answers this before you reason about it. Three layers, in order.
Protocol layer. JSON-RPC reserves -32602 for invalid params and -32603 for internal error: the first is yours, the second is theirs. HTTP encodes the same split, and RFC 9110 defines it explicitly, 4xx means the client seems to have erred while 5xx means the server is aware that it has erred.
Tool layer. A well-built server publishes a retry verdict per code. One reference table separates codes that mean change the request (not found, invalid parameter, unsupported content, forbidden scope, content private), codes that mean the service is temporarily unhealthy and retrying after a stated delay will help (circuit open, rate limited, identity pool exhausted, upstream risk control), and one code that means neither: `UPSTREAM_CHANGED`, described as a parser bug that a different request does not work around, where the correct action is to report it.
Decide with a control rather than a feeling. Replay a known-good minimal request against the same endpoint. If that also fails, the fault is on their side or somewhere on the path; if it succeeds, your request is the variable. Then change exactly one thing at a time. Also check whether the identical call succeeded earlier: a previously working request that now fails points at their side or at a changed precondition such as credentials or quota, not at your syntax. Finally, never retry 4xx-shaped failures, because they are deterministic and repetition cannot change them.
How to verify it yourself: Take one real failure and record which layer produced it: JSON-RPC code, tool-result code, or HTTP status class. Then run the control, meaning a minimal request the service documents as valid. A different outcome for the control means the service or the path is at fault; the same outcome means your request is. Next, confirm your retry policy agrees with that classification: 4xx and not-found-style codes must not be retried, 5xx and circuit-open codes may be retried after the stated delay, and upstream-changed must be reported rather than reworked. Where the classification and the policy disagree, the policy is the defect to fix.
https://www.rfc-editor.org/rfc/rfc9110.html
https://www.jsonrpc.org/specification
https://github.com/evil0ctal/douyin_tiktok_download_api/blob/4f0bed8483c35a980315d9c7b3a1d4a1119ad2b2/documents/en/12-mcp.md