错误处理

当 API 请求失败时，Poomi 返回带有相应 HTTP 状态码的 JSON 错误响应。

错误响应格式

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "人类可读的错误描述。"
  }
}

错误代码

客户端错误

HTTP 状态码	代码	描述
400	`VALIDATION_ERROR`	请求体格式错误或缺少必填字段
400	`MISSING_IMAGE`	端点需要图像输入但未提供
400	`MISSING_TEXT`	端点需要文本输入但未提供
400	`MISSING_INPUT`	端点需要图像和/或文本输入但未提供
400	`INVALID_IMAGE`	图片格式不支持或文件大小超限
401	`UNAUTHORIZED`	缺少或无效的 Authorization 请求头
401	`INVALID_KEY`	API Key 不存在
402	`INSUFFICIENT_CREDITS`	账户积分不足
403	`KEY_DISABLED`	API Key 已被禁用
403	`KEY_REVOKED`	API Key 已被撤销
403	`KEY_EXPIRED`	API Key 已过期
404	`NOT_FOUND`	端点标识不存在或未发布

服务器错误

HTTP 状态码	代码	描述
502	`AI_CALL_FAILED`	上游 AI 模型调用失败

处理错误

检查 HTTP 状态码

4xx 错误是客户端错误 — 修正请求后再重试
5xx 错误是服务器错误 — 可以使用指数退避重试

示例：代码中的错误处理

const response = await fetch('https://www.poomi.pet/api/v1/{endpoint-slug}', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pk_your_api_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ image: base64Data }),
});

if (!response.ok) {
  const { error } = await response.json();

  switch (error.code) {
    case 'INSUFFICIENT_CREDITS':
      // 提示用户充值积分
      break;
    case 'INVALID_KEY':
      // 检查 API Key 配置
      break;
    case 'AI_CALL_FAILED':
      // 重试请求
      break;
    default:
      console.error(`API error: ${error.code} - ${error.message}`);
  }
}

重试策略

对于 5xx 错误，使用指数退避：

等待 1 秒，重试
等待 2 秒，重试
等待 4 秒，重试
3 次尝试后放弃

On this page