从 404 到 200：一次 GitCode Issue 接口联调的排错记录

引子

想用脚本给代码仓自动提 Issue，第一版请求直接返回 404：Project not found。奇怪的是，仓库明明存在，页面也能正常打开。这篇文章记录一次接口联调的真实过程：从错误信息定位、路径拼接排查，到最终拿到 200 与 issue iid。

一、先看错误长什么样

第一次请求返回：

{
  "error_code": 404,
  "error_code_name": "error",
  "error_message": "Project not found:org/agent-best-practices/repos"
}

关键信息在 Project not found 后面的路径。它说明服务端把 org/agent-best-practices/repos 当成了项目名，而不是“组织下的仓库列表”。

问题出在仓库名从哪里来。第一版脚本为了省事，直接从页面上抓“链接”，结果抓到了导航链接：

/org/agent-best-practices/repos
/org/agent-best-practices/issues

这些是组织页的功能入口，不是仓库本身。把它们拼进 Issue 接口，自然 404。

二、修正仓库来源：区分“导航链接”和“项目链接”

仓库链接的形态是 /agent-best-practices/{repo}，而导航链接是 /org/... 。用正则严格限定层级，就能把它们分开：

const repos = [...new Set(
  [...document.querySelectorAll("a")]
    .map(a => a.getAttribute("href"))
    .filter(h => h && /^\/agent-best-practices\/[^/]+$/.test(h))
)]

这一步很关键：自动化里“看起来像链接”不等于“就是目标链接”。抓取前先明确 URL 结构，比事后调试便宜得多。

三、路径编码：斜杠必须转成 %2F

Issue 接口把“组织/仓库”作为一个路径参数，因此斜杠不能直接出现：

const enc = encodeURIComponent("agent-best-practices/ai-interview-swarm");
// agent-best-practices%2Fai-interview-swarm

如果直接拼 /issue/agent-best-practices/ai-interview-swarm/issues，路由会把它解析成更多层级，同样 404。

四、接口形态：不同版本走不同路径

联调时我试了三组路径，结果很典型：

• POST /api/v1/issue/{enc}/issues → 200，返回 id 与 iid；
• POST /api/v1/issue/{enc}/issue → 404（单数路径不存在）；
• POST /api/v5/repos/{enc}/issues → 1003（项目不存在）。

同一平台不同版本的内部接口路径可能完全不一样。有效做法是在浏览器上下文中发请求（复用登录态），先小范围试探，再固化成功的那一条：

const resp = await fetch(url, {
  method: "POST",
  credentials: "include",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ title, description })
});

五、请求体字段：不是所有平台都叫 body

GitHub 风格的接口用 body，而这个接口用的是 description。字段名错了不一定报错，可能只是内容为空。提交后要校验返回体：

const data = await resp.json();
if (!data.iid) throw new Error("issue 未创建：" + JSON.stringify(data));

拿到 iid（仓库内编号）和 id（全局 ID）后，才算真正创建成功。

六、把经验固化成排查清单

1. 先读错误信息：Project not found 后面往往直接写着错误路径；
2. 检查仓库名来源：导航链接 ≠ 项目链接；
3. 检查编码：组织/仓库的组合必须 URL 编码；
4. 在浏览器上下文试探接口：复用 Cookie，避免鉴权干扰；
5. 校验响应主键：iid/id 存在才算成功；
6. 失败信息落盘：保留最后一次请求与响应，便于复盘。

七、小结

这次 404 的根因不是权限，也不是网络，而是把导航链接当成了仓库路径。它提醒我们：接口联调时，先把“数据从哪来、长什么样、怎么编码”三件事确认清楚，往往比盲目重试有效得多。

最终的请求很朴素：正确的仓库路径、编码后的参数、正确的字段名，加上一条响应校验。但从 404 走到 200 的过程，值得记录下来。