错误码

Panda World API 使用标准 HTTP 状态码，并返回与 OpenAI 错误格式一致的 JSON 错误体。

错误响应格式

JSON

{
  "error": {
    "message": "Insufficient balance",
    "type": "insufficient_balance",
    "code": "insufficient_funds",
    "param": null
  }
}

HTTP 状态码

状态码	错误码	说明
200	-	成功
400	`invalid_request_error`	请求格式错误 — 检查参数、请求头或请求体
401	`authentication_error`	API 密钥无效、缺失或已被吊销
402	`insufficient_balance`	账户余额不足以处理此请求
404	`not_found`	请求的资源或模型未找到
429	`rate_limit_error`	请求过多 — 请降低频率
500	`api_error`	服务器内部错误 — 请稍后重试
502	`upstream_error`	上游模型提供方返回错误
503	`service_unavailable`	服务暂时不可用 — 维护或过载

常见错误场景

身份验证错误 (401)

JSON

{
  "error": {
    "message": "Incorrect API key provided: sk-***abc. Check your key is correct.",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

解决方法：检查你的 API 密钥是否正确且未被吊销。

余额不足 (402)

JSON

{
  "error": {
    "message": "Your account balance ($0.50) is insufficient for this request. Estimated cost: $0.75",
    "type": "insufficient_balance",
    "code": "insufficient_funds",
    "param": null
  }
}

解决方法：通过仪表盘充值。

请求频率限制 (429)

JSON

{
  "error": {
    "message": "Rate limit exceeded: 100 requests per minute",
    "type": "rate_limit_error",
    "code": "rate_limited",
    "param": null
  }
}

解决方法：在客户端实现指数退避。参考 Retry-After 响应头。

模型未找到 (404)

JSON

{
  "error": {
    "message": "The model 'gpt-4o' does not exist",
    "type": "not_found",
    "code": "model_not_found",
    "param": null
  }
}

解决方法：在我们的模型与定价页面检查正确的模型 ID。

频率限制响应头

所有 API 响应都包含频率限制头信息：

响应头	说明
`X-RateLimit-Limit`	每分钟允许的最大请求数
`X-RateLimit-Remaining`	当前窗口剩余请求数
`X-RateLimit-Reset`	窗口重置的 Unix 时间戳
`Retry-After`	重试前等待的秒数（仅 429 响应）

最佳实践

始终处理 401 错误，检查你的 API 密钥
对 429 和 5xx 错误使用带抖动的指数退避
监控余额以避免 402 错误
短暂延迟后重试 502/503 错误 — 它们通常是暂时的