> ## Documentation Index > Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt > Use this file to discover all available pages before exploring further. # ORBEXA常见问题与故障排查 > ORBEXA故障排查完整技术指南：涵盖API统一错误码格式解读、Bearer Token认证失败修复方案、Webhook投递重试机制说明、商品数据同步失败排查流程、OTR扫描超时处理方法和CSV数据导入报错的详细解决方案，帮助开发者和商家快速定位并解决集成过程中遇到的常见问题 # 故障排查指南 ## API 错误格式 所有 ORBEXA API 端点返回统一的 JSON 错误结构： ```json theme={null} { "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 参考文档](/zh/book-7/ch8-api-reference) 补全所有必填字段 | | `XSS_DETECTED` | 400 | 输入包含潜在危险的 HTML 或脚本内容 | 移除输入字段中的 HTML 标签和脚本元素 | | `FIELD_TOO_LONG` | 400 | 字符串字段超出最大长度限制 | 将值缩短至文档规定的长度以内 | ### 调试校验失败 收到 `VALIDATION_ERROR` 时，`details` 对象包含字段级错误数组： ```json theme={null} { "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 ``` ### 指数退避策略 对于自动化集成，建议实施指数退避： 1. 收到第一个 `429` 响应后，等待 `Retry-After` 指定的时长（未提供时默认等待 1 秒） 2. 重试仍返回 `429` 时，等待时间翻倍 3. 持续翻倍，直到上限 60 秒 4. 连续 5 次失败后，记录错误并触发监控告警 ## Webhook 故障排查 ### 签名无效 ```json theme={null} { "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 分钟，请检查平台的状态页面了解是否有已知故障。 ### 部分同步处理 同步部分完成时： * 已成功处理的商品会被提交并立即生效 * 失败的条目会在日志中记录具体错误详情 * 下次同步（无论是自动还是手动）仅重新处理失败的条目 ### 重试机制 自动同步重试遵循以下时间表： 1. 第一次重试：失败后 5 分钟 2. 第二次重试：第一次重试后 15 分钟 3. 第三次重试：第二次重试后 60 分钟 4. 三次重试均失败后，同步标记为失败并发送通知 ## 数据导入错误 ### 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 端点的健康情况。如果某个端点显示"降级"或"离线"，问题可能是平台层面的，而非您的账户所独有。 ### 诊断清单 联系技术支持时，请准备以下信息以加快问题定位： 1. **错误码和 HTTP 状态** -- 来自 API 响应 2. **请求时间戳** -- 请注明时区 3. **端点地址** -- 返回错误的 API 路径 4. **请求体** -- 请脱敏 API 密钥等敏感信息 5. **账户邮箱** -- 关联 ORBEXA 控制台的邮箱地址 ### 支持渠道 * **知识库** -- 浏览 [ORBEXA 知识库](/zh/book-7/index) 获取详细指南 * **控制台帮助** -- 使用控制台内置的帮助组件获取上下文指引 * **邮件支持** -- 通过控制台页脚中的邮箱地址联系技术支持团队 * **状态页面** -- 实时监控平台健康状况和故障更新 *** 完整的 API 端点目录和认证详情请参阅[第8章：API 参考与速率限制](/zh/book-7/ch8-api-reference)。控制台功能详解请参阅[第9章：商家控制台](/zh/book-7/ch9-dashboard)。