> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误

> GetQR API 返回的错误格式和错误代码。

> [!NOTE]
>
> GetQR API 目前处于 Beta 阶段，仅向部分工作区开放。正式发布前，细节可能会有所变化。

GetQR API 使用标准 HTTP 状态码。成功的请求返回 `2xx`。失败的请求返回 `4xx` 或 `5xx`，并附带一个说明出错原因的 JSON 响应体。

## 错误格式

所有错误都使用相同的结构：固定的代码、易读的消息，以及指向该代码说明的链接。

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized: Invalid API key.",
    "doc_url": "https://getqr.com/account/api-docs#error-unauthorized"
  }
}
```

**error.code** `string` *required*

固定的、供程序读取的错误代码。请在代码中使用它，而不是消息文本。请参阅[错误代码](#错误代码)。

**error.message** `string` *required*

易读的问题描述。措辞可能会变化。

**error.doc\_url** `string` *required*

指向您 GetQR 账户中 API 文档内该错误代码说明的链接。

## 错误代码

| 代码 | HTTP 状态 | 何时出现 |
| - | - | - |
| `bad_request` | 400 | 请求格式有误：请求体不是有效的 JSON，`Authorization` 请求头缺少 `Bearer ` 前缀，或资源的当前状态不允许该操作（例如取消已完成的批量创建）。 |
| `unauthorized` | 401 | API 密钥缺失或无效，例如密钥已被重新生成。 |
| `forbidden` | 403 | 工作区所有者的订阅未生效，或您在工作区中的角色无权执行此操作。 |
| `exceeded_limit` | 403 | 您已达到套餐限额。在 Single QR 套餐中，工作区已有一个二维码时再创建或复制二维码，或者发起批量创建，都会出现此错误。 |
| `not_found` | 404 | 资源不存在或不属于您的工作区，端点不存在，或您的工作区未启用 API。 |
| `method_not_allowed` | 405 | 该端点存在，但不接受此 HTTP 方法。`Allow` 响应头列出了它接受的方法。 |
| `conflict` | 409 | 请求与现有数据冲突：短链接路径已被占用，使用相同 `Idempotency-Key` 的请求仍在处理中，定时报告与现有报告重叠，或批量创建的压缩包尚未就绪。 |
| `invite_pending` | 409 | 您已受邀加入该工作区，但尚未加入。使用 API 密钥的请求不会返回此代码：密钥所属的工作区一定是您已加入的工作区。 |
| `invite_expired` | 410 | 您加入该工作区的邀请已过期。出于同样的原因，使用 API 密钥的请求不会返回此代码。 |
| `unprocessable_entity` | 422 | 请求体或查询参数未通过校验。消息会指出出错的字段及问题所在。请参阅[校验错误](#校验错误)。 |
| `rate_limit_exceeded` | 429 | 该 API 密钥在当前时间窗口内的请求次数已用完。请参阅[速率限制](https://docs.getqr.com/zh/api/rate-limits.md)。 |
| `internal_server_error` | 500 | 我们这边出了问题。请稍后重试；如果问题持续出现，请联系支持团队。 |

## 校验错误

请求体或查询参数未通过校验时，API 会返回 `422`。消息以 `<issue>: <field>: <details>` 的格式描述第一个无效字段：

```json theme={null}
{
  "error": {
    "code": "unprocessable_entity",
    "message": "too_big: pageSize: Max page size is 100.",
    "doc_url": "https://getqr.com/account/api-docs#error-unprocessable_entity"
  }
}
```

嵌套字段使用点号表示法，例如 `link.url`。

## 处理错误

* 根据 `error.code` 而不是 `error.message` 进行分支处理。
* 不要原样重试 `4xx` 错误：请先修正请求。例外情况是请求仍在处理中时返回的 `409`，以及 `429`。
* 收到 `429` 时，请等待 `Retry-After` 响应头中给出的秒数。请参阅[速率限制](https://docs.getqr.com/zh/api/rate-limits.md#超出限制时)。
* 对 `5xx` 错误使用指数退避进行重试。

## 常见问题

> [accordion] 每个请求都返回 404 "This endpoint is not available."
>
> API 目前处于 Beta 阶段，您的工作区尚未启用。

> [accordion] 404 "This endpoint does not exist."
>
> 路径有误。请对照各端点页面检查路径，并确认它以 `/api/v1/` 开头。

> [accordion] 403 "Access denied: This account does not have an active subscription."
>
> 工作区所有者的订阅已结束。所有者重新订阅后，API 密钥即可再次使用。

> [accordion] 403 "API access is not available for this role."
>
> 您在工作区中的角色是查看者。只有工作区所有者和编辑者可以使用 API。

## 后续步骤

> [card] [速率限制](https://docs.getqr.com/zh/api/rate-limits.md)

> [card] [身份验证](https://docs.getqr.com/zh/api/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.