---
title: "HTTP 状态码"

doc_type: static
doc_category: static
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/http-status-code'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/http-status-code.md'
---
# HTTP 状态码​

HTTP 状态码是 SHOPLINE API 的重要组成部分。对于每次 API 调用，响应中会包含一个 HTTP 状态码，用于指示请求结果。

------

## **状态码说明**

### 类别

HTTP 状态码由三位数字组成，其中第一位数字定义了响应的类别。

SHOPLINE API 使用以下状态码类别：

- **2xx**：成功。服务器已收到、理解并接受请求。
- **3xx**：重定向。客户端需采取进一步操作以完成请求，如跳转至新地址。
- **4xx**：客户端错误。请求无法处理，通常由参数格式错误、鉴权失败或资源不存在等客户端原因引起。
- **5xx**：服务端错误。请求本身没有问题，但 SHOPLINE 服务端发生异常。通常为临时性故障，可稍后重试或联系技术支持。

### 错误响应

当 API 请求出错时，除了返回状态码（4xx 或 5xx）外，响应中还会包含错误详情，具体结构如下：

- **HTTP 状态行**
    - **状态码**：用于标识具体错误的 HTTP 状态码，如 `404`、`500`。详见下方的 [状态码列表](#状态码列表)。
    - **状态文本**：对 HTTP 状态码的简要英文说明，如 `Not Found`。

- **响应体**：包含 `errors` 字段，用于提供详细的上下文信息，如参数校验失败或业务逻辑错误。

示例：

```markdown
HTTP/1.1 404 Not Found

{
    "errors": "The product does not exist."
}
```

------

## 状态码列表

下表列出了 SHOPLINE API 使用的 HTTP 状态码：

| **状态码** | **状态文本**                   | **详细说明**                                                 |
| ---------- | ------------------------------ | ------------------------------------------------------------ |
| **200**    | OK                             | 已成功处理该请求。                                           |
| **201**    | Created                        | 请求已完成，并创建新资源。                                   |
| **202**    | Accepted                       | 请求已被接受，但尚未处理。                                   |
| **303**    | See Other                      | 临时重定向，要求客户端改用 `GET` 方法请求新 URI。            |
| **400**    | Bad Request                    | 服务器无法理解该请求，通常是由于语法错误、`Content-Type` 未设置为 `application/json` 或参数类型不对。 |
| **401**    | Unauthorized                   | 身份认证失败。未提供凭证，或凭证有误或已过期。需重新获取授权或刷新凭证。 |
| **402**    | Payment Required               | 商店目前被冻结，商家需要登录 [SHOPLINE 商家后台](https://admin.myshopline.com/) 并支付未结余额。 |
| **403**    | Forbidden                      | 服务器拒绝执行请求。                                         |
| **404**    | Not Found                      | 未找到请求的资源。                                           |
| **405**    | Method Not Allowed             | 接口不存在或已经下线。                                       |
| **406**    | Not Acceptable                 | 服务器无法返回请求的 `Accept` 头所指定的内容类型。           |
| **412**    | Precondition Failed            | 先决条件失败，如请求体中包含高风险脚本等被拦截的内容。       |
| **422**    | Unprocessable Entity           | 请求正文格式正确但包含语义错误。响应体的 `errors` 参数中会提供详细信息。 |
| **423**    | Locked                         | 商店目前已锁定。常见原因：超过 API 请求限制、账户存在泄露或欺诈风险。需联系 SHOPLINE 技术支持。 |
| **429**    | Too Many Requests              | 请求被限流，应用已超出接口访问的频次限制。                   |
| **433**    | Request Blocked                | 请求被识别为攻击请求或 IP 被加入黑名单。                     |
| **434**    | Excessive Rate Limit Surpassed | 请求频率严重超限，触发了 SHOPLINE 安全限流机制。             |
| **435**    | Challenge Collapsar Attack     | 触发了 Challenge Collapsar（CC 攻击）防护策略。              |
| **436**    | Security Policy Triggered      | 请求被拦截，因为请求内容触发了 SHOPLINE 安全策略。           |
| **500**    | Internal Error                 | SHOPLINE 发生内部错误。需稍后重试，或联系 SHOPLINE 技术支持。 |
| **501**    | Not Implemented                | 接口在当前商店不可用，可能因为该接口仅对内部应用开放或为将来保留。 |
| **503**    | Service Unavailable            | 服务器当前不可用。需稍后重试。                               |
| **504**    | Gateway Timeout                | 服务器无法及时响应请求，导致超时。若是批量或复杂请求，建议分解为多个较小的请求。 |