请求没有带 API Key
错误内容包含：401、API_KEY_REQUIRED、API key is required
为什么会报错：客户端没有发送 Key，或者 Key 填错了位置。
解决办法：把 Portdan Key 完整粘贴到当前供应商的 API Key 输入框，检查 Portdan 请求地址和启用的供应商，保存后从右下角托盘完全退出 Codex，再打开测试一次。
API 请求错误
复制客户端显示的完整报错，点右上角的 粘贴报错，粘贴后搜索。报错只有 403、429 或 503 时，把它后面的英文也一起复制。
401、403 和 API Key
API Key 无效
错误内容包含：401 Unauthorized、INVALID_API_KEY、authentication_error、Invalid API key
为什么会报错：Codex 里保存的 Key 不对、复制不完整，或者客户端仍在使用旧 Key。
解决办法：从 Portdan 重新复制 Key，整段替换旧 Key；再检查 Portdan 请求地址和当前启用的供应商。保存后从右下角托盘完全退出 Codex，再打开测试一次。
展开其他 401 报错
API Key 已停用
错误内容包含：401、API_KEY_DISABLED、API key is disabled
为什么会报错：这枚 Key 已在 Portdan 停用，客户端继续使用它就会被拒绝。
解决办法：在 Portdan 启用原 Key，或者创建一枚新 Key 并替换旧 Key。确认请求地址和启用的供应商后，从右下角托盘完全退出 Codex，再打开测试一次。
Key 所属账号不可用
错误内容包含：401、USER_NOT_FOUND、User associated with API key not found、USER_INACTIVE、User account is not active
为什么会报错：创建这枚 Key 的账号已不存在、未激活或已停用。
解决办法：登录一个状态正常的 Portdan 账号，创建新 Key，再替换客户端里的旧 Key。保存后完全退出 Codex，再打开测试一次。
修改后的配置没有生效
错误内容包含：401，换了 Key 后报错完全不变
为什么会报错：Codex 仍在使用旧 Key、错误的 Portdan 请求地址，或者当前启用的不是 Portdan。
解决办法：在 CC Switch 编辑已有的 Portdan，核对 Key 和请求地址，确认已经启用 Portdan。保存后从右下角托盘完全退出 Codex，再打开测试一次；不要删除整个配置文件。
API Key 已过期
错误内容包含：403、API_KEY_EXPIRED、API key 已过期
为什么会报错：这枚 Key 已超过设置的有效期。
解决办法：在 Portdan 延长 Key 的有效期，或者创建新 Key 并替换客户端里的旧 Key。保存后完全退出 Codex，再打开测试一次。
Portdan 余额不足
错误内容包含：403、INSUFFICIENT_BALANCE、billing_error、Insufficient account balance
为什么会报错：当前分组使用的 Portdan 余额不足。
解决办法：先查看 Portdan 余额是否充足。余额不足就充值；余额充足时，检查这枚 Key 选择的分组是否正确，改完后再测试一次。
没有可用订阅
错误内容包含：403、SUBSCRIPTION_NOT_FOUND、subscription_error、No active subscription found for this group
为什么会报错：这枚 Key 选择了套餐分组，但账号没有对应的有效订阅。
解决办法：打开 Portdan 的【我的订阅】页面查看状态。订阅已过期就续费；选错分组就把 Key 改到当前订阅对应的分组，再测试一次。
Key 绑定的分组已删除或停用
错误内容包含：403、GROUP_DELETED、API Key 所属分组已删除、GROUP_DISABLED、API Key 所属分组已停用
为什么会报错：这枚 Key 还绑定着一个已经删除或停用的旧分组。
解决办法：旧 Key 已无法继续使用时，创建一枚新 Key，选择分组列表里实际显示的可用分组，再把客户端改成新 Key。
当前账号不能使用这个分组
错误内容包含：403、GROUP_NOT_ALLOWED、API Key 所属专属分组不再允许当前用户使用
为什么会报错：这枚 Key 选择的分组不在当前账号可用范围内。
解决办法：打开 API 密钥页面，只使用分组列表里实际显示的分组。需要其他分组时，创建一枚选择了正确分组的新 Key，再替换客户端里的旧 Key。
403 只显示 permission_error
错误内容包含：403 Forbidden、permission_error、permission denied
为什么会报错：当前 Key、分组或模型没有这次请求需要的权限，但报错没有写出更具体的原因。
解决办法：检查 Key、Portdan 请求地址、当前分组和模型。都正确时，把消息分支到新会话，只发送一次；仍是同一条报错时，停止发送。
Key 的 IP 白名单或黑名单拒绝了请求
错误内容包含：403、ACCESS_DENIED、Access denied. Your IP is ...
为什么会报错：这枚 Key 设置了 IP 白名单或黑名单，当前网络的出口 IP 不符合规则。
解决办法：打开 Portdan 的 API 密钥页面，编辑这枚 Key 的 IP 白名单和黑名单；也可以切换到规则允许的网络。保存后再测试一次。
展开其他 Key 检查报错
连续使用错误 Key，暂时被限制
错误内容包含：429、INVALID_AUTH_RATE_LIMITED、invalid auth rate limited
为什么会报错：客户端在短时间内连续发送了无效 Key。
解决办法：先停止发送，重新检查 Key、Portdan 请求地址和启用的供应商。等待 30 秒，从右下角托盘完全退出 Codex，再打开并只测试一次。
Key 或订阅状态处理失败
错误内容包含：500、INTERNAL_ERROR、Failed to validate API key、SUBSCRIPTION_MAINTENANCE_FAILED
为什么会报错：Portdan 暂时没有完成这次 Key 或订阅状态检查。
解决办法：不要连续发送。等待 30 秒后测试一次；仍失败时停止发送并保留完整报错。
API Key 检查服务繁忙
错误内容包含：503、API_KEY_AUTH_OVERLOADED、API key authentication is temporarily overloaded
为什么会报错：当前检查 Key 的请求太多，这不代表 Key 已失效。
解决办法：不用更换 Key。等待 30 秒后测试一次；也可以把当前会话分支到新会话继续。
400 请求内容有问题
请求格式不对
错误内容包含：400 Bad Request、invalid_request_error、Failed to parse request body
为什么会报错：客户端发出的内容缺少必填项，或者格式坏了。
解决办法：Codex 用户确认 CC Switch 选择了 Responses，请求地址填 https://portdan.com。其他客户端打开对应教程，检查协议、Base URL 和必填字段。保存后重启客户端，只测试一次。
展开其他 400 报错
Key 放错位置
错误内容包含：api_key_in_query_deprecated、API key in query parameter is deprecated
为什么会报错：客户端把 Key 放进了网址参数。
解决办法：回到客户端的 API Key 输入框填写，不要把 Key 拼在请求地址后面。
404 地址或模型不存在
请求地址不存在
错误内容包含：404 Not Found、route not found、not_found_error
为什么会报错：客户端使用了错误的 Portdan 地址，或给根地址多加了一段路径。
解决办法：Codex 和 CC Switch 使用 https://portdan.com。其他客户端按自己的教程填写 Base URL，保存后重启客户端。
模型不存在或当前分组不能用
错误内容包含：model_not_found、model not found、unknown model、No such model
为什么会报错：模型名写错了，或这枚 Key 的分组不支持该模型。
解决办法：去模型广场找到这个模型，只选择页面列出的分组。回到 Codex，在输入框下方切换成可用模型。
413 内容太长
本次发送的内容太大
错误内容包含：413、Request body too large、payload too large
为什么会报错：这次发送的文字或附件超过了接口允许的大小。
解决办法：删除大附件，把长内容拆成几次发送，再试一次。
对话历史太长
错误内容包含：context_length_exceeded、maximum context length、context window
为什么会报错：当前会话的历史、附件和新问题加起来太长。
解决办法：把当前消息分支到新会话，或新建会话，只带这次需要的内容。
429 请求太多或额度用完
临时请求过多
错误内容包含：429 Too Many Requests、rate_limit_error、rate_limit_exceeded、Too many pending requests、exceeded retry limit, last status: 429 Too Many Requests
为什么会报错：你短时间发了太多请求、同时运行的任务太多，或客户端已经自动尝试了多次。
解决办法：先停掉其他请求。报错写了等待时间就按它等；没有就等 30 秒。Codex 可以把当前消息分支到新会话，只发送一次。
余额或套餐额度用完
错误内容包含：insufficient_quota、API_KEY_QUOTA_EXHAUSTED、USAGE_LIMIT_EXCEEDED、API_KEY_RATE_5H_EXCEEDED、API_KEY_RATE_1D_EXCEEDED、API_KEY_RATE_7D_EXCEEDED
为什么会报错：Portdan 余额不足，或套餐在本次时间段内的额度已经用完。
解决办法：打开 Portdan 查看余额和【我的订阅】。余额不足就充值；订阅过期就续费；套餐仍有效时，检查 Key 是否选择了对应分组。
500 服务器处理失败
服务器没有完成这次请求
错误内容包含：500 Internal Server Error、api_error、Internal error
为什么会报错：服务处理这次请求时出错了。
解决办法：等 30 秒，把当前消息分支到新会话后再试一次。多个短会话都报 500 时，先停止发送。
502 模型服务没有正常返回
模型服务没有返回有效结果
错误内容包含：502 Bad Gateway、upstream_error、Upstream service temporarily unavailable、Upstream request failed
为什么会报错：Portdan 已经接到请求，但模型服务没有正常完成。
解决办法：等 30 秒，把消息分支到新会话后再试一次。仍然失败就换当前分组支持的另一个模型。
503 暂时无法使用
当前分组不能使用这个模型
错误内容包含：503 No available channel for model [模型名] under group [分组名]。模型名和分组名会按你的配置变化。
为什么会报错：这枚 Key 的分组没有可用的该模型。
解决办法：去模型广场找到该模型，选择页面实际列出的分组，或直接切换到当前分组已经支持的模型。
当前没有可用服务
错误内容包含：503 Service Unavailable、No available accounts、暂无可用服务
为什么会报错：当前模型暂时没有可用服务。
解决办法：等 30 秒后再试一次，或换当前分组支持的另一个模型。
当前使用人数较多
错误内容包含：We're currently experiencing high demand...、overloaded_error、Upstream service overloaded, please retry later、529 Overloaded
为什么会报错：当前模型的可用容量已经满了。
解决办法：等 30 秒，把消息分支到新会话后再试一次。急用时切换到当前分组支持的另一个模型。
504 等待模型超时
模型回复超时
错误内容包含：504 Gateway Timeout
为什么会报错：服务已经开始等待模型，但没有在规定时间内拿到完整回复。
解决办法：等 30 秒，把任务拆短或切换到当前分组支持的另一个模型，再发送一次。
展开 520 至 524 报错
520 服务返回了无法识别的结果
错误内容包含：520 Web Server Returned an Unknown Error
为什么会报错：服务返回的内容不完整，网页无法正常显示结果。
解决办法：等 30 秒，把消息分支到新会话后再试一次。
521 服务暂时无法连接
错误内容包含：521 Web Server Is Down
为什么会报错：网页暂时连不上 Portdan 服务。
解决办法：等 30 秒后刷新一次。仍然报 521 时，先停止操作。
522 建立连接超时
错误内容包含：522 Connection Timed Out
为什么会报错：Portdan 服务端没有在规定时间内建立连接。
解决办法：等 30 秒后刷新一次。仍然报 522 时停止刷新，按本页底部的方式提交。
523 无法到达服务
错误内容包含：523 Origin Is Unreachable
为什么会报错：服务入口暂时找不到 Portdan 服务端。
解决办法：等 30 秒后刷新一次。仍然报 523 时停止刷新，按本页底部的方式提交。
524 等待回复超时
错误内容包含：524 A Timeout Occurred
为什么会报错：连接已经建立，但模型处理时间太长，网页没有等到结果。
解决办法：等 30 秒，把任务拆短或切换模型，再分支到新会话发送一次。
Failed to read request body
请求发送途中断了
错误内容包含：Failed to read request body、invalid_request_error
为什么会报错：客户端还没发完请求，网络或代理就断开了。模型还没有开始回复。
解决办法：依次尝试 TUN、换节点、直连和手机热点。从托盘完全退出 Codex，再打开一个短会话发送一次 hi。
展开其他请求发送问题
客户端发出了空请求
错误内容包含：Request body is empty
为什么会报错：客户端没有把问题内容发出来。
解决办法：新建一个会话，输入 hi 后再发送。仍然出现时，更新或重新下载客户端。
回复中途断开
客户端先断开了连接
错误内容包含：499、client_gone、canceled、client closed request
为什么会报错：你点了停止，电脑休眠了，或网络在回复结束前断开。
解决办法：保持电脑唤醒，换稳定网络，把消息分支到新会话。从托盘完全退出 Codex 后再发送一次。
回复没有正常结束
错误内容包含：stream disconnected before completion、stream closed before response.completed
为什么会报错：回复还没结束，网络、代理或客户端连接就断了。
解决办法：打开 TUN，换节点或网络，把消息分支到新会话。从托盘完全退出 Codex，再打开后发送一次。
等待回复太久
错误内容包含：idle timeout waiting for SSE、SSE timeout
为什么会报错：客户端等了一段时间，仍然没有收到新内容。
解决办法：换网络，把长任务拆短，再分支到新会话发送一次。
回复最后显示失败
错误内容包含：response.failed、event: error、没有 response.completed
为什么会报错：连接虽然建立了，但模型没有完成这次回复。
解决办法：先看报错后面有没有 429、503 或余额提示，有就按对应错误处理。没有时等 30 秒，把消息分支到新会话再试一次。
反复显示 Reconnecting
Codex 一直重新连接
错误内容包含：Reconnecting... 1/5、Reconnecting... 5/5
为什么会报错：Codex 无法稳定连接服务。系统代理和不稳定节点经常触发这个问题。
解决办法：打开 TUN，换节点、直连或手机热点。从托盘完全退出 Codex，再打开新会话测试。
EOF、DNS 和连接重置
网络没有建立连接
错误内容包含：EOF、DNS、TLS、ECONNRESET、connection reset、network error
为什么会报错：电脑没有连上服务，或连接中途被网络、运营商或代理断开。
解决办法：把系统时间设为自动，依次尝试 TUN、换节点、直连和手机热点，然后重启客户端。
408 和 timeout_error
发送或等待时间太长
错误内容包含：408 Request Timeout、request timed out、timeout_error
为什么会报错：上传问题或等待回复超过了允许时间。
解决办法：换稳定网络，删除大附件，把任务拆短，再分支到新会话发送一次。
WebSocket 报错
WebSocket 没有连通
错误内容包含：426 Upgrade Required、WebSocket close 1008、1011、1013
为什么会报错：客户端尝试使用 WebSocket，但请求地址或网络没有完成连接。
解决办法：先在 CC Switch 确认当前供应商。OpenAI Official 可以使用 WebSocket；Portdan 的 Responses 流式请求走 HTTP/SSE。切换供应商后，完全退出 Codex，再重新打开。OpenAI Official 报错时，换一个能稳定连接 WebSocket 的 VPN 节点。
仍然无法解决
把报错截图、发生时间、客户端名称、模型和分组发给管理员。