错误处理

Pixapi 返回 HTTP 状态码和机器可读错误码。你的应用应区分用户可修正错误和临时基础设施错误。

错误格式

{
  "error": {
    "code": "model_unavailable",
    "message": "The selected model is temporarily unavailable.",
    "request_id": "req_..."
  }
}

分类处理

分类	示例	处理方式
请求错误	invalid_request, model_not_found	修正请求校验。
认证错误	unauthorized	要求提供有效 API Key。
计费错误	insufficient_credits	展示 Credits 或 Billing。
策略错误	prompt_rejected	要求用户修改输入。
临时错误	rate_limited, model_unavailable	使用退避重试。

重试模式

只对临时错误使用指数退避。

const delays = [500, 1000, 2000];
for (const delay of delays) {
  const res = await callPixapi();
  if (res.ok) return res;
  if (![429, 500, 503].includes(res.status)) break;
  await new Promise((resolve) => setTimeout(resolve, delay));
}

Request id

可用时记录 request_id。提交 支持工单 时带上它，团队就能定位失败调用，而不需要把原始 prompt 暴露给无关系统。