V1 OpenAPI 错误码

本文集中维护 Sugumart OpenAPI V1 的错误响应、恢复方式和重试规则。各 Endpoint 文档说明业务上下文，本文件作为错误码处理的统一入口。

Base Path: /openapi/v1

错误响应格式

错误响应使用 V1 统一信封。success 固定为 false；程序应以 HTTP Status 和稳定的 code 分支，不得依赖 message 文案。data 仅在需要时返回可安全使用的结构化辅助信息。

request_id 为可选字段，仅当请求携带 X-SGM-Request-Id Header 时返回，并与响应 Header X-Request-Id 相同。

json

{
  "success": false,
  "code": "order_shipment_data_incomplete",
  "message": "Shipment data is incomplete",
  "data": {
    "missing_fields": ["items[0].weight"]
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

字段	类型	必填	说明
`success`	boolean	是	固定为 `false`
`code`	string	是	稳定的机器可读错误码
`message`	string	是	人类可读错误说明；内容可能优化，程序不得据此判断错误类型
`data`	object \| null	否	结构化错误辅助信息；字段随 `code` 确定，不保证所有错误都返回
`request_id`	string	否	请求携带 `X-SGM-Request-Id` 时返回，与 `X-Request-Id` Header 相同

重试分类

分类	含义	调用方动作
否	原请求未经修改时不应重试	修正参数、权限、配置或业务状态后重新发起
查询后	写请求结果或外部副作用可能不确定	先查询对应资源；仅在确认操作未生效后重试
是	临时故障，可重试	使用指数退避并限制最大次数；存在 `Retry-After` 时优先遵循

无论错误是否标记为可重试，调用方都不得无限重试。对 POST 请求发生网络超时、500、502 或 503 时，应优先查询商品、订单、回调配置或物流仓的最新状态，避免重复创建外部资源。

通用错误码

HTTP	`code`	可重试	调用方动作
400	`validation_error`	否	根据 `data` 或 Endpoint 字段约束修正请求
401	`invalid_token`	否	Access Token 无效或已过期；应用后端串行刷新一次，刷新失败再重新浏览器认证
401	`unauthorized`	否	Access Token 无效或已过期；应用后端串行刷新一次，刷新失败再重新浏览器认证
403	`forbidden`	否	检查当前 Token 绑定店铺及其权限，不能通过原请求重试恢复
403	`shop_not_initialized`	否	引导卖家登录 `https://seller.sugumart.com/` 完成 KYC 和支付绑定
403	`shop_suspended`	否	店铺已暂停，停止调用并联系 Sugumart 客服
404	`not_found`	否	检查资源 ID；该错误也用于隐藏其他租户的资源是否存在
400	`invalid_state`	否	重新查询资源，并按最新状态决定后续操作
429	`rate_limit_exceeded`	是	等待 `Retry-After` 指定秒数后重试
500	`internal_error`	查询后	写请求先查询资源状态；查询请求可指数退避重试

invalid_token 与 unauthorized 都表示 Access Token 无效或已过期。调用方应使用相同的单次刷新流程处理；只有刷新失败时才清除凭证并重新浏览器认证，不应根据二者推断不同的权限状态。

认证和店铺配置

HTTP	`code`	可重试	调用方动作
400	`invalid_callback_url`	否	改用合法 HTTPS URL，移除 fragment 和内嵌账号密码
401	`invalid_token`	否	串行刷新一次 Access Token；刷新失败时清除整组凭证并重新认证
403	`forbidden`	否	检查 Token 所绑定店铺的权限或联系平台支持
404	`shop_not_found`	否	确认 Token 已绑定可用店铺

商品和媒体

HTTP	`code`	可重试	调用方动作
400	`category_not_selectable`	否	逐级查询类目并选择 `selectable=true` 的末级类目
400	`invalid_media_type`	否	使用对应用途支持的图片格式
400	`image_file_too_large`	否	压缩图片至对应用途大小限制以内
400	`invalid_image_dimensions`	否	调整图片宽高至对应用途允许范围
400	`sku_structure_locked`	否	保留已发布商品的露天规格结构
400	`cannot_delete_published_sku`	否	保留 SKU UUID `id` 并设置 `status=false`
400	`invalid_sku_id`	否	使用商品详情返回且属于当前商品的 SKU UUID
400	`product_incomplete`	否	补齐 `data.missing_fields` 或提交审核所需资料
409	`product_review_state_changed`	否	重新获取商品详情后再保存
503	`upload_service_unavailable`	是	指数退避后重新申请上传 URL；不要重复 PUT 已成功上传的文件

平台类目和店铺商品分类

HTTP	`code`	可重试	调用方动作
404	`category_not_found`	否	重新从一级类目开始查询，确认 `g_class` 仍启用
404	`store_class_not_found`	否	重新获取当前店铺商品分类列表
404	`product_category_not_found`	否	重新获取商品分类列表，不再对原 ID 操作
409	`product_category_in_use`	否	先将使用该分类的商品移出或改设其他分类
502	`ruten_store_class_mutation_failed`	查询后	先查询商品分类列表，确认创建或删除是否已生效
502	`invalid_ruten_store_class_response`	是	指数退避后重新获取商品分类列表

订单和取消交易

HTTP	`code`	可重试	调用方动作
404	`order_not_found`	否	检查 Sugumart 订单 ID 和当前店铺
409	`order_not_shippable`	否	查询订单详情，以 `available_actions` 判断是否仍可出货
409	`order_not_cancellable`	否	查询订单详情，以 `available_actions` 判断是否仍可取消
409	`fulfillment_already_exists`	否	使用订单详情返回的当前履约，不再创建第二个履约
409	`cancellation_conflict`	否	查询当前 `cancellation`，不得覆盖内容不同或买家发起的申请
409	`cancellation_not_pending`	否	查询订单详情，确认是否仍有等待确认的买家取消申请
409	`cancellation_already_rejected`	否	该申请不能再次确认，按最新取消状态处理
502	`ruten_provider_error`	查询后	先查询商品或订单状态，确认露天操作是否生效

物流和仓库

HTTP	`code`	可重试	调用方动作
400	`carrier_required`	否	补充平台支持的 `carrier_code`
404	`warehouse_not_found`	否	重新获取可用仓库列表并选择有效 code
409	`warehouse_unavailable`	否	改选当前启用且物流商可用的仓库
409	`warehouse_role_mismatch`	否	集运仓选择 `consolidation`，退货仓选择 `return`
409	`warehouse_provider_mismatch`	否	两个仓库改为同一物流商
422	`shipment_configuration_incomplete`	否	根据 `data.missing_fields` 补齐店铺物流配置
422	`order_shipment_data_incomplete`	否	根据 `data.missing_fields` 补齐订单、清关、SKU 重量或申报资料
503	`shipment_provider_error`	查询后	先查询订单履约；未建立履约时再指数退避重试

错误 `data` 约定

错误响应中的 data 只返回调用方可安全使用的结构化信息，不包含 Secret、完整证件号码或内部堆栈。

`code`	`data` 字段	类型	说明
`validation_error`	`fields`	object	可选；字段名到校验错误数组的映射
`product_incomplete`	`missing_fields`	string[]	缺失或不符合提交审核要求的商品字段路径
`shipment_configuration_incomplete`	`missing_fields`	string[]	缺失的店铺物流配置字段路径
`order_shipment_data_incomplete`	`missing_fields`	string[]	缺失的订单、SKU 或清关字段路径
`rate_limit_exceeded`	`retry_after`	integer	建议等待秒数，与 `Retry-After` Header 一致

字段路径使用点号和数组下标，例如 skus[0].weight、items[0].product_id。调用方不得假设 data 一定存在；自动处理应以 code 为主。

V1 OpenAPI 错误码 ​

错误响应格式 ​

重试分类 ​

通用错误码 ​

认证和店铺配置 ​

商品和媒体 ​

平台类目和店铺商品分类 ​

订单和取消交易 ​

物流和仓库 ​

错误 data 约定 ​