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 相同。

{
  "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 审核；Payoneer 未绑定不阻断 OpenAPI
403	shop_suspended	否	店铺已暂停，停止调用并联系 Sugumart 客服
404	not_found	否	检查资源 ID；该错误也用于隐藏其他租户的资源是否存在
400	invalid_state	否	重新查询资源，并按最新状态决定后续操作
413	request_entity_too_large	否	缩小请求体后重新发送；图片文件应通过媒体预签名 URL 上传，不应放入 JSON 请求体
429	rate_limit_exceeded	是	等待 Retry-After 指定秒数后重试
500	internal_error	查询后	写请求先查询资源状态；查询请求可指数退避重试

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

认证和店铺配置

HTTP	code	可重试	调用方动作
400	invalid_callback_url	否	改用合法 HTTP/HTTPS URL，移除 fragment 和内嵌账号密码
401	invalid_token	否	串行刷新一次 Access Token；刷新失败时清除整组凭证并重新认证
400	unauthorized_client	否	按应用类型改用 Authorization Code 或 Client Credentials
401	invalid_client	否	检查 App ID、启用状态、当前 Client Secret，以及凭证是否发送到匹配的测试或生产 Auth 环境；修正后重新发起完整授权流程
400	redirect_uri_not_allowed	否	在 Admin 登记完整回调地址，并确保浏览器授权与 Token 兑换使用完全相同的 redirect_uri
400	invalid_grant	否	作废当前授权状态；使用新的 state、PKCE verifier 和授权码重新发起浏览器授权
403	forbidden	否	检查 Token 所绑定店铺的权限或联系平台支持
404	shop_not_found	否	确认 Token 已绑定可用店铺
404	callback_not_configured	否	先为当前店铺设置通知回调

商品和媒体

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	duplicate_sku_target	否	移除通过 id 或 spec_id 重复定位的 SKU
400	sku_not_published	否	仅更新已有露天 spec_id 的已发布 SKU
400	at_least_one_active_sku_required	否	更新后至少保留一个 status=true 的 SKU
400	product_incomplete	否	补齐 data.missing_fields 或提交审核所需资料
400	product_main_image_limit_exceeded	否	将商品主图删除至最多 9 张后重新提交审核
409	product_review_state_changed	否	重新获取商品详情后再保存
409	ruten_sku_structure_conflict	否	露天规格结构在 Sugumart 之外发生变化；停止自动覆盖并联系管理员核对规格绑定
503	upload_service_unavailable	是	指数退避后重新申请上传 URL；不要重复 PUT 已成功上传的文件
502	ruten_sku_update_failed	查询后	SKU 本地修改已经保存但露天渠道同步失败；查询商品最新状态，再决定是否重试

平台类目和店铺商品分类

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	否	旧契约错误码；当前订单出货对无法识别的公司使用 OTHER，不会仅因此返回本错误
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 补齐店铺物流配置；出现 seller_return_warehouse 时设置主要卖家大陆退货仓
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[]	缺失或不符合提交审核要求的商品字段路径
product_main_image_limit_exceeded	field	string	固定为 images
product_main_image_limit_exceeded	max_count	integer	固定为 9
product_main_image_limit_exceeded	actual_count	integer	当前商品实际主图数量
ruten_sku_update_failed	local_updated	boolean	固定为 true，表示本地 SKU 修改已经保存
ruten_sku_update_failed	updated_sku_ids	string[]	本次已保存的 Sugumart SKU UUID
ruten_sku_update_failed	failed_step	string	失败的渠道步骤：spec_info、price 或 stock
ruten_sku_update_failed	completed_steps	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 为主。

跨境运输方式

HTTP Status	code	条件与处理
400	transport_mode_not_supported	所选方式未在物流商配置中开启；查询仓库 transport_modes 后重新选择
409	transport_mode_conflict	本地失败履约重试显式传入不同方式；沿用原方式或省略该字段

transport_mode 非法枚举、null 或空字符串统一返回 400 validation_error。