错误 - GetQR Docs

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

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

错误格式

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

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

string

必填

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

string

必填

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

string

必填

指向您 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 密钥在当前时间窗口内的请求次数已用完。请参阅速率限制。
`internal_server_error`	500	我们这边出了问题。请稍后重试；如果问题持续出现，请联系支持团队。

校验错误

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

{
  "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 响应头中给出的秒数。请参阅速率限制。
对 5xx 错误使用指数退避进行重试。

常见问题

每个请求都返回 404 "This endpoint is not available."

API 目前处于 Beta 阶段，您的工作区尚未启用。

404 "This endpoint does not exist."

路径有误。请对照各端点页面检查路径，并确认它以 /api/v1/ 开头。

403 "Access denied: This account does not have an active subscription."

工作区所有者的订阅已结束。所有者重新订阅后，API 密钥即可再次使用。

403 "API access is not available for this role."

您在工作区中的角色是查看者。只有工作区所有者和编辑者可以使用 API。

API

错误

错误格式

错误代码

校验错误

处理错误

常见问题

后续步骤

速率限制

身份验证

​错误格式

​错误代码

​校验错误

​处理错误

​常见问题

​后续步骤

速率限制

身份验证

错误格式

错误代码

校验错误

处理错误

常见问题

后续步骤