Checklist

本公开清单用于排查用户侧可见问题，帮助你在联系支持前收集关键信息。本文不会暴露 内部 origin 细节，也不包含管理员专用 runbook。

联系支持时，请提供时间戳、公开 URL 或 API path、HTTP status、可用的 request ID 和已脱敏客户端日志。不要发送原始 API key 或完整 Authorization header。

DNS 问题

现象：

• 域名无法解析。
• curl 报告 Could not resolve host。
• 只有某个网络或地区受影响。

检查：

DNS 检查

dig docs.codexpertise.com
dig api.codexpertise.com

如果 DNS 失败，请换一个网络重试；如果你控制客户端机器，可以清理本地 DNS cache； 同时记录失败的 resolver 或地区。

TLS 问题

现象：

• 浏览器显示证书警告。
• curl 报告证书、handshake 或协议错误。
• 公司代理访问其他网站正常，但访问 Codexpertise 失败。

检查：

TLS 检查

curl -Iv https://docs.codexpertise.com/en/
curl -Iv https://api.codexpertise.com/

如果 TLS 只在代理后失败，请向网络管理员确认是否存在 TLS inspection、cipher 限制 或自定义 trust store。

CloudFront 5xx

现象：

• 公开 Codexpertise 域名返回 500、502、503 或 504。
• 从不同地区重试得到不同结果。

请收集时间戳、URL、status code，以及响应 header 中可公开分享的 request ID。 不要在报告中包含内部 host 或 secret。私有路由链路由运维团队检查。

Nginx 502

现象：

• 公开站点返回 502 Bad Gateway。
• 某个 path 失败，但其他 Codexpertise 页面仍可访问。

用户侧请确认公开 URL，以及 /en/、/zh/ 和具体 API path 是否同样失败。 管理员级 Nginx 检查不放在公开用户文档中。

sub2api Upstream Error

现象：

• API 返回 5xx Upstream Error。
• Relay 有响应，但 provider-side 请求失败。

请使用 backoff 重试，并尝试更小的请求。如果问题持续，请联系支持并提供时间戳、 API path、HTTP status 和可用的 request ID。不要发送 API key。

TODO: verify against sub2api。最终 upstream error code 和 request ID 字段需要验证后 再写入稳定文档。

Authorization Header 丢失

现象：

• API 请求返回 401 Unauthorized。
• 同一个 key 在一个客户端可用，在另一个客户端失败。

检查：

Header pattern

Authorization: Bearer YOUR_API_KEY

常见原因包括环境变量未加载、代理规则移除了 header、header 名写错、复制时带入 空白字符，或使用了已撤销的 key。

Streaming interrupted

现象：

• 输出开始后中途停止。
• 客户端报告 broken pipe、timeout、cancelled request 或 incomplete event stream。

只有操作可安全重复时才重试；同时测试非 streaming 请求，减少响应长度，并检查 客户端、网络或代理是否设置了过短 timeout。如果稳定复现，请联系支持并提供时间戳 和客户端 timeout 设置。

Slow response

现象：

• 请求最终成功，但耗时明显长于预期。
• Coding-agent 任务等待长响应后才继续。

请尝试更小的 prompt、降低并发、换网络测试，并比较 streaming 与非 streaming 行为。 大型请求的上游生成可能天然较慢；如果反复延迟，请带上时间戳和请求 path 联系支持。