# 错误码目录

错误响应里的 `error.code` 是稳定的，按它编程判断，别解析文案。`error.docUrl` 指到这一行。

| 错误码 | 含义 | 怎么修 |
| --- | --- | --- |
| `AUTH_MISSING_TOKEN` | 缺少认证 token | 在 Authorization 头带 `Bearer <token>`（/api/v1 不认 ?token= 查询串）。token 用 POST /api/v1/auth/token（请求体 client_id + client_secret）换。 |
| `AUTH_INVALID_TOKEN` | token 无效 | token 格式或签名不对。重新用 POST /api/v1/auth/token 取一个；确认没截断、没多空格。 |
| `AUTH_EXPIRED` | token 已过期 | token 有效期到了。重新取一个；建议客户端在快过期时自动续。 |
| `SCOPE_DENIED` | 无此操作权限 | 你的渠道角色不包含该能力。到「套餐与申请」选一档申请开通（reader / trader / full），对接人审批后即时生效。 |
| `WAREHOUSE_DENIED` | 无此仓库权限 | 你的渠道不在该仓的白名单。请管理员在后台把该仓加进你渠道的仓白名单，或清空白名单=不限仓。 |
| `AUTHZ_UNAVAILABLE` | 授权服务暂不可用 | 授权服务暂时不可用。稍后重试；若持续，带上 requestId 联系对接人。 |
| `VALIDATION_FAILED` | 请求参数不合法 | 按 error.param 指出的字段修正。各端点字段规格见 /swagger。 |
| `NOT_FOUND` | 查无此项 | 款号/SKU/单号不存在或拼写有误。核对后重试。 |
| `OWNERSHIP_DENIED` | 无权访问该单据 | 该单据不属于你的渠道。只能查自己渠道的订单/发货单/锁单。 |
| `UPSTREAM_ERROR` | 上游 ERP 出错 | 上游 ERP 暂时异常。稍后重试；带上 requestId 联系运维可定位到具体那次。 |
| `UPSTREAM_TIMEOUT` | 上游超时 | 上游 ERP 响应慢或不通。稍后重试。 |
| `INTERNAL` | 网关内部错误 | 网关自身异常（少见）。带上 requestId 联系运维。 |
| `ADMIN_UNAUTHORIZED` | 管理员口令不对 | 检查 x-admin-token 是否是服务器 .env 里的 ADMIN_TOKEN。 |
| `ADMIN_DISABLED` | 后台未启用 | 服务器未设 ADMIN_TOKEN。设置后重启即可用。 |
| `IDEMPOTENCY_IN_PROGRESS` | 同一幂等请求正在处理 | 上一次带相同 Idempotency-Key 的请求还没跑完。稍等重试即可，不要换 key（换了就可能重复下单）。 |
| `IDEMPOTENCY_MISMATCH` | Idempotency-Key 被复用 | 这个 key 之前用在内容不同的请求上。每一笔业务用一个新 key（建议 UUID 或你自己的订单号）。 |
| `IDEMPOTENCY_INVALID_KEY` | Idempotency-Key 不合法 | key 长度上限 255 字符。建议用 UUID。 |
| `RATE_LIMITED` | 调用额度用完 | 看响应头 RateLimit-Remaining / Retry-After，等一下再试。拉全仓库存很贵（一次 60 点），改用增量口 /Changes?since= 只花 1 点。确实不够用找对接人提额。 |
| `BAD_REQUEST` | 请求有误 | 检查请求方法、路径、body 是否正确。 |
| `READ_ONLY_MODE` | 本环境为只读模式 | 这台服务器有意关闭了对上游 ERP 的写入（WRITES_ENABLED=0），用于安全测试。查询照常可用。需要真正下单请用生产环境。 |
| `ENDPOINT_GONE` | 接口已下线 | 接口面已迁到 /api/v1/**（路径小写、参数 snake_case）。error.message 里给了对应的新地址；完整清单见 /reference 或 /llms.txt。 |
| `WAREHOUSE_UNKNOWN` | 没有这个仓库 | 仓码用 GET /api/v1/warehouses 里列出的那几个（AU / AUSYD2 / AUSYD1 / CN / CHNZJ1），不再有 AuStock 这类别名。 |
| `UPSTREAM_REJECTED` | 上游拒绝了这次请求 | ERP 没有接受这笔业务（库存不足、单号不存在、字段不合规…），原因在 error.message 里。修正后重试；反复出现请把 request_id 发给对接人。 |
| `AUTH_BAD_CREDENTIALS` | 凭证不对 | 渠道方式：核对 client_id 和 client_secret（口令只在发放时显示一次，丢了找管理员重发）。OMS 账号方式（grant_type=password）：核对 OMS 网站的登录账号和密码。想先试可以用 sandbox / sandbox。 |
| `AUTH_LOCKED` | 登录失败次数过多，已临时锁定 | 同一 OMS 账号连续输错密码会锁 15 分钟。确认账号密码后再试；想先试可以用 sandbox / sandbox。 |
| `DUPLICATE_SUSPECTED` | 疑似重复的代发单 | 同一收件人 + 同一 SKU 短时间内重复提交会被上游判重。确认要下就换一个 client_order_number，或稍后再试。 |
| `OMS_LOGIN_REQUIRED` | 这个接口要用 OMS 账号登录 | 用 POST /api/v1/auth/token 带 grant_type=password + OMS 账号密码换 token（渠道号 + 口令换的 token 用不了下单链，因为配货规则跟着 OMS 账号走）。 |
| `SHIPPING_REQUIRED` | 缺物流信息 | 下批发单要指定发货方式：GET /api/v1/shipping-methods 挑一个 shipping_method_id 传进 shipping；送货的再从 GET /api/v1/addresses 挑一个 address_id。也可以在 OMS 网站「用户 → 偏好设置」里设默认值。 |

## 错误响应

```json
{
  "error": {
    "code": "WAREHOUSE_DENIED",
    "message": "无此仓库权限",
    "hint": "…",
    "request_id": "r_8f2c1a",
    "doc_url": "https://connect.everugg.net.au/errors/WAREHOUSE_DENIED"
  }
}
```

HTTP 状态码就是成功 / 失败的判据；`error.code` 稳定不变，`message` 与 `hint` 跟随 `Accept-Language`。

---
Markdown 源: https://connect.everugg.net.au/reference/errors.md?lang=zh · 网页版: https://connect.everugg.net.au/reference?sec=errors&lang=zh