故障排查指南

API 错误格式

所有 ORBEXA API 端点返回统一的 JSON 错误结构：

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "描述具体错误原因的可读文本",
    "details": {}
  }
}

code 字段是机器可读的错误标识，适用于程序化处理。message 字段提供人类可读的说明。details 对象为可选项，在可用时提供额外上下文，例如哪些字段未通过校验。

认证错误

错误码	HTTP 状态	原因	解决方案
`UNAUTHORIZED`	401	API 密钥缺失或无效	检查 `X-API-Key` 请求头是否包含控制台中的有效密钥
`EXPIRED_API_KEY`	401	API 密钥已过期	在控制台”设置 > API 密钥”中生成新密钥
`SESSION_EXPIRED`	401	登录会话已超时	重新登录以获取新会话
`FORBIDDEN`	403	当前用户权限不足	确认账户角色是否具备访问目标资源的权限

常见认证陷阱

请求头格式错误 — 确保使用正确的请求头格式。API 密钥使用 X-API-Key 头，而 OAuth 令牌使用 Authorization: Bearer 方式。
密钥中含有空白字符 — 从控制台复制 API 密钥时可能引入前导或尾随空格，使用前请确保已清除多余空白。
密钥已被吊销 — 已吊销的密钥会立即返回 UNAUTHORIZED。如果密钥被团队成员吊销，请生成替代密钥。

数据校验错误

错误码	HTTP 状态	原因	解决方案
`VALIDATION_ERROR`	400	请求体或查询参数未通过格式校验	查看 `details` 字段获取具体的字段级错误
`INVALID_DOMAIN`	400	域名格式不符合预期	确保域名为有效主机名，不含协议前缀（如应为 `example.com` 而非 `https://example.com`）
`MISSING_REQUIRED_FIELD`	400	缺少必填参数	按照 API 参考文档补全所有必填字段
`XSS_DETECTED`	400	输入包含潜在危险的 HTML 或脚本内容	移除输入字段中的 HTML 标签和脚本元素
`FIELD_TOO_LONG`	400	字符串字段超出最大长度限制	将值缩短至文档规定的长度以内

调试校验失败

收到 VALIDATION_ERROR 时，details 对象包含字段级错误数组：

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "fields": [
        { "field": "price", "message": "Must be a positive number" },
        { "field": "currency", "message": "Must be a valid ISO 4217 currency code" }
      ]
    }
  }
}

逐一检查 fields 数组中的每条记录，修正对应值后重试。

速率限制

概述

ORBEXA 通过速率限制保障平台的公平使用和稳定运行。超出限制时，API 返回 HTTP 状态 429 和错误码 RATE_LIMIT_EXCEEDED。

各端点类型的速率限制

端点类别	限额	窗口
UCP 端点	100 次	每分钟
API 端点	60 次	每分钟
认证端点	10 次	每分钟
Webhook 端点	200 次	每分钟
WordPress 插件	每 IP 3 次	每分钟

Retry-After 响应头

被限速时，响应包含 Retry-After 头，指示等待秒数：

HTTP/1.1 429 Too Many Requests
Retry-After: 30

指数退避策略

对于自动化集成，建议实施指数退避：

收到第一个 429 响应后，等待 Retry-After 指定的时长（未提供时默认等待 1 秒）
重试仍返回 429 时，等待时间翻倍
持续翻倍，直到上限 60 秒
连续 5 次失败后，记录错误并触发监控告警

Webhook 故障排查

签名无效

{
  "success": false,
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "Webhook signature verification failed"
  }
}

HTTP 状态：400 原因：请求头中的 HMAC 签名与根据请求体和 Webhook 密钥计算出的预期值不匹配。

各平台的签名请求头

不同平台使用不同的签名头和编码方式：

平台	签名头	算法
Shopify	`X-Shopify-Hmac-Sha256`	HMAC-SHA256 (Base64)
WooCommerce	`X-WC-Webhook-Signature`	HMAC-SHA256 (Base64)
Stripe	`Stripe-Signature`	HMAC-SHA256 (Hex)
ORBEXA	`X-OTR-Signature`	HMAC-SHA256 (Hex)

常见 Webhook 故障

密钥轮换不同步：如果在平台侧更换了 Webhook 密钥但未同步更新 ORBEXA（或反之），所有签名验证都会失败。请确保双方密钥完全一致。 编码格式不匹配：部分平台使用 Base64 编码签名，另一些使用十六进制编码。请确认验证逻辑与具体平台使用的编码格式一致。 请求体格式差异：Webhook 签名基于原始请求体计算。如果接收端先解析 JSON 再重新序列化后才进行验证，签名将无法匹配。请始终对原始字节流进行验证。 投递重试：ORBEXA 对投递失败的 Webhook 最多重试 3 次，间隔逐次递增。如果端点短暂不可用，恢复后可能收到同一事件的多次投递，请使用事件 ID 进行去重处理。

平台集成连接问题

Shopify OAuth

问题	原因	解决方案
state 参数无效	OAuth state 令牌已过期或被篡改	从 ORBEXA 控制台重新发起连接流程
令牌交换失败	Shopify API 在令牌交换时返回错误	确认 Shopify 店铺地址正确且店铺处于活跃状态
API 凭证缺失	未授权必要的 Shopify API 权限范围	断开后重新连接，确保批准所有请求的权限
店铺未找到	Shopify 店铺地址无法解析	确认店铺子域名正确（如 `yourstore.myshopify.com`）

WooCommerce REST API

问题	原因	解决方案
API 密钥不匹配	Consumer Key 或 Secret 不正确	在 WooCommerce 后台”设置 > 高级 > REST API”中重新生成 API 密钥
REST API 未启用	WooCommerce REST API 被禁用或被屏蔽	在 WooCommerce 设置中启用 REST API，同时检查固定链接是否设置为”朴素”模式
SSL 证书错误	WooCommerce 店铺使用自签名或过期证书	在服务器上安装有效的 SSL 证书

连接状态说明

状态	含义
已连接（绿色）	集成正常，最近一次同步成功
警告（黄色）	集成已连接，但最近同步遇到非致命错误
已断开（红色）	集成失去连接，可能需要重新认证
待配置（灰色）	集成设置尚在进行中

同步失败

平台 API 速率限制

外部平台有各自的速率限制。当 ORBEXA 在同步过程中遇到平台速率限制时：

同步自动暂停，等待平台冷却期后自动重试
如果速率限制持续超过 10 分钟，同步标记为部分完成，日志中记录中断位置

服务不可用 (503)

同步过程中收到 503 响应，表示平台或下游服务暂时不可用。 解决方案：等待几分钟后手动触发同步。如果问题持续超过 30 分钟，请检查平台的状态页面了解是否有已知故障。

部分同步处理

同步部分完成时：

已成功处理的商品会被提交并立即生效
失败的条目会在日志中记录具体错误详情
下次同步（无论是自动还是手动）仅重新处理失败的条目

重试机制

自动同步重试遵循以下时间表：

第一次重试：失败后 5 分钟
第二次重试：第一次重试后 15 分钟
第三次重试：第二次重试后 60 分钟
三次重试均失败后，同步标记为失败并发送通知

数据导入错误

CSV 导入校验

CSV 导入器在处理前逐行校验，常见问题包括：

错误	原因	解决方案
缺少必填列	CSV 文件缺少 `title` 或 `price` 列头	确保 CSV 至少包含 `title` 和 `price` 列
价格值无效	价格字段包含非数字字符或为负数	使用正数小数，不含货币符号（如 `29.99`）
库存为负	库存数量低于零	将库存设为 `0` 或正整数
币种代码无效	币种值不是有效的 ISO 4217 代码	使用标准三字母代码，如 `USD`、`EUR`、`GBP`
行数据过长	字段值超出最大长度	描述不超过 10,000 字符，标题不超过 500 字符

必填字段与格式要求

字段	是否必填	格式	最大长度
`title`	是	文本字符串	500 字符
`price`	是	正数小数	—
`currency`	否（默认使用账户币种）	ISO 4217 三字母代码	3 字符
`description`	否	文本字符串（不允许 HTML）	10,000 字符
`inventory`	否（默认为 0）	非负整数	—
`image_url`	否	有效的 HTTPS 地址	2,000 字符
`category`	否	文本字符串	200 字符
`sku`	否	字母数字字符串	100 字符

域名验证问题

CNAME 未传播

现象：域名状态长时间停留在”待验证”。 解决方案：

DNS 传播根据服务商和 TTL 设置不同，可能需要 48 小时
使用 DNS 查询工具确认 CNAME 记录是否正确创建
确保同一主机名下不存在冲突的 A 或 AAAA 记录

DNS 记录错误

现象：域名验证失败，提示”记录不匹配”。 解决方案：

确认 CNAME 目标值与 ORBEXA 控制台中显示的值完全一致
检查 DNS 记录中是否有多余的尾部点号或其他字符
部分服务商会自动追加区域名称，请核实完整记录值

SSL 证书待签发

现象：域名显示”已验证”但 HTTPS 无法正常访问。 解决方案：

DNS 验证通过后，SSL 证书会自动签发
证书签发通常在 15 分钟内完成
若超过 1 小时仍未签发，请移除域名后重新添加以重启流程

商务交易错误

错误码	HTTP 状态	原因	解决方案
`CHECKOUT_FAILED`	400	结算会话创建失败	检查所有必填结算字段是否已提供且商品有库存
`NEGATIVE_PRICE`	422	商品价格为负数	在目录中将商品价格修正为正数
`INVALID_CURRENCY`	422	币种代码不是有效的 ISO 4217 代码	使用标准三字母币种代码（如 `USD`、`EUR`、`JPY`）
`PRODUCT_NOT_FOUND`	404	引用的商品 ID 不存在	核实商品 ID，确认商品未被删除
`OUT_OF_STOCK`	409	请求数量超过可用库存	减少数量或等待补货

错误码速查表

错误码	HTTP	触发场景	处理方式
`UNAUTHORIZED`	401	API 密钥无效或缺失	检查请求头中的 API 密钥
`EXPIRED_API_KEY`	401	密钥已过期	在控制台生成新密钥
`SESSION_EXPIRED`	401	登录超时	重新登录
`FORBIDDEN`	403	角色权限不足	联系账户所有者获取权限
`VALIDATION_ERROR`	400	请求体格式错误	查看 `details.fields` 获取详情
`INVALID_DOMAIN`	400	域名格式错误	去掉协议前缀和路径
`MISSING_REQUIRED_FIELD`	400	缺少必填参数	按 API 文档补全字段
`XSS_DETECTED`	400	输入含危险内容	移除 HTML 和脚本标签
`FIELD_TOO_LONG`	400	字段值超长	缩短字段值
`RATE_LIMIT_EXCEEDED`	429	请求过于频繁	按 `Retry-After` 头等待
`SCAN_IN_PROGRESS`	409	重复扫描请求	等待当前扫描完成
`DOMAIN_NOT_FOUND`	404	无扫描结果	先提交扫描请求
`INVALID_SIGNATURE`	400	Webhook HMAC 不匹配	确认双方密钥一致
`CHECKOUT_FAILED`	400	结算创建失败	校验所有结算参数
`NEGATIVE_PRICE`	422	价格为负	修正商品价格
`INVALID_CURRENCY`	422	非 ISO 4217 币种	使用标准币种代码
`PRODUCT_NOT_FOUND`	404	商品 ID 不存在	核实商品 ID
`OUT_OF_STOCK`	409	库存不足	减少数量或补货

获取帮助

控制台通知

全局性问题和计划维护窗口会通过控制台通知系统发布。在排查个别错误前，请先检查导航栏上的通知铃铛图标是否有活跃告警。

协议端点状态

控制台首页的端点状态面板实时显示 UCP、ACP 和 MCP 端点的健康情况。如果某个端点显示”降级”或”离线”，问题可能是平台层面的，而非您的账户所独有。

诊断清单

联系技术支持时，请准备以下信息以加快问题定位：

错误码和 HTTP 状态 — 来自 API 响应
请求时间戳 — 请注明时区
端点地址 — 返回错误的 API 路径
请求体 — 请脱敏 API 密钥等敏感信息
账户邮箱 — 关联 ORBEXA 控制台的邮箱地址

支持渠道

知识库 — 浏览 ORBEXA 知识库获取详细指南
控制台帮助 — 使用控制台内置的帮助组件获取上下文指引
邮件支持 — 通过控制台页脚中的邮箱地址联系技术支持团队
状态页面 — 实时监控平台健康状况和故障更新

完整的 API 端点目录和认证详情请参阅第8章：API 参考与速率限制。控制台功能详解请参阅第9章：商家控制台。

​故障排查指南

​API 错误格式

​认证错误

​常见认证陷阱

​数据校验错误

​调试校验失败

​速率限制

​概述

​各端点类型的速率限制

​Retry-After 响应头

​指数退避策略

​Webhook 故障排查

​签名无效

​各平台的签名请求头

​常见 Webhook 故障

​平台集成连接问题

​Shopify OAuth

​WooCommerce REST API

​连接状态说明

​同步失败

​平台 API 速率限制

​服务不可用 (503)

​部分同步处理

​重试机制

​数据导入错误

​CSV 导入校验

​必填字段与格式要求

​域名验证问题

​CNAME 未传播

​DNS 记录错误

​SSL 证书待签发

​商务交易错误

​错误码速查表

​获取帮助

​控制台通知

​协议端点状态

​诊断清单

​支持渠道

故障排查指南

API 错误格式

认证错误

常见认证陷阱

数据校验错误

调试校验失败

速率限制

概述

各端点类型的速率限制

Retry-After 响应头

指数退避策略

Webhook 故障排查

签名无效

各平台的签名请求头

常见 Webhook 故障

平台集成连接问题

Shopify OAuth

WooCommerce REST API

连接状态说明

同步失败

平台 API 速率限制

服务不可用 (503)

部分同步处理

重试机制

数据导入错误

CSV 导入校验

必填字段与格式要求

域名验证问题

CNAME 未传播

DNS 记录错误

SSL 证书待签发

商务交易错误

错误码速查表

获取帮助

控制台通知

协议端点状态

诊断清单

支持渠道