报错字典 / claude-code / HTTP 429

并发稍高就被限流

没有开提示缓存，或者重试没有退避。

原始报错

2026-11-05
APIError: 429 {\"error\":{\"message\":\"Rate limit exceeded\"}}

原因

两个原因叠加：前缀缓存没开（每次请求都把整段上下文重算一遍），以及客户端遇到 429 直接重打、没有指数退避。

解法

  1. 在接入源侧开 Prompt 缓存，并确认中转层原样透传 cache_control 标记，中转层一旦改写请求体，缓存全部失效，成本反而更高
  2. 看返回里的 cache_read_input_tokens，为 0 就说明缓存没生效
  3. 客户端侧配指数退避重试，Codex 用 request_max_retries / stream_max_retries
  4. 并发确实超了，就降并发而不是加并发

同一工具的其他问题

HTTP 401配好了却仍然走官方端点 claude-code HTTP 404接入后立刻返回 404 claude-code MCP_TOOL_SEARCH_DISABLEDMCP 工具列表是空的 claude-code