跳转到主要内容
此页面由 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 401/403/409——这些场景发生在响应信封被套用之前，或代表真正的 HTTP 语义。

​
验证失败

几乎每个写入端点都会经过 FluentValidation。在此被拦截的任何内容——缺少必填字段、值超出范围、国家代码无效、批量超出上限、以 Custom(...) 检查表达的业务规则违反——都会归并到同一个错误代码：
Wire HTTPmeta.statusmeta.errorCodemeta.error
200400VALIDATION_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.errorCodeWire HTTPmeta.status何时出现
TRACKING_ALREADY_EXIST200400您提交的 trackingNumber 已被另一条活跃记录占用。最常见于 Create FBA shipment ——同一个 Amazon 追踪号被重复提交；也可能发生在直接传入 tracking 值的退件运货单 / 重发(resend)创建上。meta.error 携带冲突记录的标识数据。
ACCOUNT_IS_BLOCKED200403您的 API 账户已被封锁（例如欠款、违反条款）。所有写入端点都会失败，直到 Return Helper 客服解除封锁。meta.error.message 含有人类可读的原因。请联系 support@returnhelper.com。
S3_OBJECT_NOT_FOUND_OR_NOT_PUBLIC_READ200404需要从 S3 拉取文件的端点（通常是 VAS 附件或面单工件）无法读取该对象。请确认您之前上传的文件仍然存在且可访问。
UPLOAD_FILE_TO_S3_FAIL200500需要上传文件到 S3 的端点失败。瞬时基础设施问题——请用相同的幂等键重试。
REQUEST_CUSTOM_DOMAIN_FAIL200500调用自定义域名服务的面单/品牌相关端点失败。瞬时——请重试。

​
认证与访问控制失败

这些不是软错误。它们会以真实的 HTTP 状态码返回，因为它们在正常请求管线之前（或之外）产生。
Wire HTTPmeta.statusmeta.errorCode何时出现
401401nullx-rr-apikey 或 x-rr-apitoken 缺失、格式错误，或未匹配到任何活跃账户。meta.error.message 为 "Missing request header" 或类似消息。
403403null抛出了 RrForbiddenException ——您的账户已认证但未被授权执行此动作（例如尝试读取其他租户的记录）。meta.error.message 是人类可读的。

​
冲突与未找到

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

​
建议的客户端处理

伪代码示例： 
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 通过客服报告。