错误代码 - Return Helper API

此页面由 AI 自动翻译。如有任何疑问或不一致之处，请以英文版本为准。

每个 API 响应都使用标准信封（correlationId + meta + payload — 见错误处理）。当出现错误时，meta.errorCode 是机器可读的错误键。本页列出 User 与 Public API 可能产生的全部值。

如何阅读本页

Wire HTTP 列是响应实际到达时的 HTTP 状态码。 meta.status 列是响应体内部的应用层状态。 meta.errorCode 列是您在客户端代码中进行分支判断的值。 meta.error 列描述每条错误细节的形态。本 API 的大多数错误路径会返回 HTTP 200，并把逻辑状态放在 meta.status 中（软错误约定）。少数场景下会返回真实的 HTTP 400/401/403/409——这些场景发生在响应信封被套用之前，或代表真正的 HTTP 语义。

验证失败

几乎每个写入端点都会经过 FluentValidation。在此被拦截的任何内容——缺少必填字段、值超出范围、国家代码无效、批量超出上限、以 Custom(...) 检查表达的业务规则违反——都会归并到同一个错误代码：

Wire HTTP	`meta.status`	`meta.errorCode`	`meta.error`
`200`	`400`	`VALIDATION_FAILED`	以请求属性名为键的对象 → 以逗号连接的错误消息列表。对于批量端点（例如 `/api/Recall/createRecallByReturnInventoryId`），`jobEntryList` 内的条目会单独露出，便于您定位是哪一项失败。

样本响应体：

{
  "correlationId": "0HNLB2U6T1QG1:00000001",
  "meta": {
    "status": 400,
    "data": {},
    "errorCode": "VALIDATION_FAILED",
    "error": {
      "returnInventoryId": "'return Inventory Id' must not be empty."
    }
  }
}

检查 meta.error——键名告诉您哪些字段有问题。

业务规则与资源错误

这些是请求在结构上有效，但与当前数据状态、您的账户，或支撑基础设施冲突时由业务逻辑抛出的错误。每种都带有不同的 errorCode，便于您据此分支处理。

`meta.errorCode`	Wire HTTP	`meta.status`	何时出现
`TRACKING_ALREADY_EXIST`	`200`	`400`	您提交的 `trackingNumber` 已被另一条活跃记录占用。最常见于 Create FBA shipment ——同一个 Amazon 追踪号被重复提交；也可能发生在直接传入 tracking 值的退件运货单 / 重发(resend)创建上。`meta.error` 携带冲突记录的标识数据。
`ACCOUNT_IS_BLOCKED`	`200`	`403`	您的 API 账户已被封锁（例如欠款、违反条款）。所有写入端点都会失败，直到 Return Helper 客服解除封锁。`meta.error.message` 含有人类可读的原因。请联系 `support@returnhelper.com`。
`S3_OBJECT_NOT_FOUND_OR_NOT_PUBLIC_READ`	`200`	`404`	需要从 S3 拉取文件的端点（通常是 VAS 附件或面单工件）无法读取该对象。请确认您之前上传的文件仍然存在且可访问。
`UPLOAD_FILE_TO_S3_FAIL`	`200`	`500`	需要上传文件到 S3 的端点失败。瞬时基础设施问题——请用相同的幂等键重试。
`REQUEST_CUSTOM_DOMAIN_FAIL`	`200`	`500`	调用自定义域名服务的面单/品牌相关端点失败。瞬时——请重试。

认证与访问控制失败

这些不是软错误。它们会以真实的 HTTP 状态码返回，因为它们在正常请求管线之前（或之外）产生。

Wire HTTP	`meta.status`	`meta.errorCode`	何时出现
`401`	`401`	`null`	`x-rr-apikey` 或 `x-rr-apitoken` 缺失、格式错误，或未匹配到任何活跃账户。`meta.error.message` 为 `"Missing request header"` 或类似消息。
`403`	`403`	`null`	抛出了 `RrForbiddenException` ——您的账户已认证但未被授权执行此动作（例如尝试读取其他租户的记录）。`meta.error.message` 是人类可读的。

冲突与未找到

不常见但有可能遇到：

Wire HTTP	`meta.status`	`meta.errorCode`	何时出现
`200`	`404`	`null`	抛出了 `RrInvalidException` 或 `RrNotfoundException` ——您引用的资源（按 ID）不存在，或不属于您的账户。`meta.error.message` 是人类可读的。
`409`	`409`	`null`	抛出了 `DuplicateTransactionException` ——您提交的状态改变请求被幂等层识别为正在进行或已完成的请求的重复。`meta.error` 含 `transactionType`、`headId`、`uniqueChargeKey`、`message`。请视为无操作——原始请求已成功。

幂等键失败

以下情况适用于在写入类端点发送 x-returnhelper-idempotency-key 请求头时，并且会以真实的 HTTP 状态码返回。

Wire HTTP	`meta.status`	`meta.errorCode`	何时出现
`400`	`400`	`IDEMPOTENCY_KEY_INVALID`	键不符合「1–128 个字符，且仅由英文字母、数字、`_`、`.`、`:`、`-` 组成」的规则。
`409`	`409`	`IDEMPOTENCY_REQUEST_IN_PROGRESS`	使用相同键的请求仍在执行中。请待其完成后再重试。
`409`	`409`	`IDEMPOTENCY_KEY_ALREADY_USED`	使用相同键的请求已在验证时间窗内完成。请视为无操作——原始请求已处理完毕。

键的作用范围是单一账户加上单一 HTTP 方法与路由，因此相同的键值可在不同端点重复使用而不会冲突。

建议的客户端处理

伪代码示例：

response = call(endpoint, body)

if response.status == 401:
  reauth or alert ops
elif response.status == 403:
  surface meta.error.message — account or permission issue
elif response.status == 409:
  treat as success (idempotency replay) — do NOT retry
elif response.status == 200:
  meta = response.body.meta
  if meta.errorCode == 'VALIDATION_FAILED':
    surface meta.error map to the user — field-level messages
  elif meta.errorCode == 'TRACKING_ALREADY_EXIST':
    handle duplicate — likely already created on a previous attempt
  elif meta.errorCode == 'ACCOUNT_IS_BLOCKED':
    halt all calls, alert ops, do not retry
  elif meta.errorCode in ('UPLOAD_FILE_TO_S3_FAIL', 'REQUEST_CUSTOM_DOMAIN_FAIL'):
    retry with the same idempotency key (transient infra)
  elif meta.errorCode == 'S3_OBJECT_NOT_FOUND_OR_NOT_PUBLIC_READ':
    re-upload the source file, then retry
  elif meta.status == 200 and meta.errorCode is null:
    success — read the payload at the top level
  elif meta.status == 404 and meta.errorCode is null:
    resource not found — the ID is wrong or out of scope

correlationId 出现在每一个响应中。请始终把它记到日志里——这是 Return Helper 客服把某一次请求追溯到内部系统的方式。

错误代码定义位置

本页记录的错误代码来自 ReturnRequestApiModel.RrException 命名空间中的 RrErrorCode 常量。如果您遇到本页未列出的 errorCode 值，请将其视为未文档化的内部错误，并附上 correlationId 通过客服报告。

​如何阅读本页

​验证失败

​业务规则与资源错误

​认证与访问控制失败

​冲突与未找到

​幂等键失败

​建议的客户端处理

​错误代码定义位置

如何阅读本页

验证失败

业务规则与资源错误

认证与访问控制失败

冲突与未找到

幂等键失败

建议的客户端处理

错误代码定义位置