为了帮助用户更高效地排查和解决调用过程中遇到的问题，本文档整理了 PPIO API 平台常见错误码的定义、原因分析及处理建议。

​
错误码 400

描述：请求参数不正确。
解决方法：
请根据返回的错误信息提示，检查并调整请求参数格式、字段名称或取值范围，确保请求体符合 API 接口文档规范。

​
错误码 401

描述：API Key 设置不正确或未设置。
解决方法：

  • 检查是否传入了正确的 API Key；
  • 确保 API Key 是最新有效的；
  • 如使用环境变量或配置文件，请确认调用时已正确读取。

​
错误码 403

描述：权限不足。
解决方法：

  • 请确认当前 API Key 所绑定账户是否具备调用该模型的权限；
  • 某些模型可能要求通过实名认证后才能使用：
    • 登录控制台查看账户的实名认证状态；
    • 若当前账户未实名，请先完成实名认证；
    • 如有其他已实名账户，请使用其下 API Key 发起请求。

​
错误码 429

描述：触发了 Rate Limit（调用频率限制）。
解决方法：

  • 根据错误信息，区分是 TPM（每分钟 Token 限制）还是 RPM（每分钟请求次数）被触发；
  • 可参考平台的 Rate Limits 文档；
  • 如需提升速率限制，请联系支持申请调整或使用认证账户发起请求。

​
错误码 503 / 504

描述：服务端超时或不可用，通常与系统负载或流控有关。

​
原因归因：

  • 模型服务所在节点负载过高（GPU / CPU）；
  • 非流式请求生成时间过长，超过网关（Nginx / API Gateway）的 timeout 配置；
  • 下游依赖服务（如 Redis、模型引擎）不可用；
  • 限流组件触发高峰保护策略，返回 503。

​
解决方法：

用户侧建议：

  • 增加重试机制：建议使用指数退避策略，避免短时间内重复压测；
  • 改为流式请求：Streaming 模式可边生成边返回 token，减少整体延迟，有效降低长文本生成失败率；
  • 优化调用配置：如通过自建代理调用，请确保 client_timeout 与 proxy_timeout 不低于 60 秒；
  • 错峰调用：如遇高并发场景，可稍后再尝试或避开高峰时段。

服务端优化建议（供平台运营参考）：

  • 加强模型服务的负载监控与自动扩容机制；
  • 网关层设置更合理的 proxy_read_timeout；
  • 设计更精细的限流规则（如优先级队列、核心业务优先保活）；
  • 搭配 Prometheus + Alertmanager 配置 503/504 异常告警。

​
错误码 500

描述：服务器内部错误，通常为后端服务异常或模型引擎崩溃。
解决方法：

  • 该类问题通常无法由用户自行解决，建议联系平台支持团队排查后端日志与资源状态；
  • 同时可尝试更换请求模型或降级服务重试。

如遇其他未列明错误，建议：

  • 首先参考 API 返回中的 message 字段；
  • 然后查看控制台或日志的调用轨迹；
  • 最终，如问题持续存在，请提交工单或联系技术支持获取帮助。