错误

当 API 请求失败时，badges.ninja 会返回 JSON 错误响应以及相应的 HTTP 状态码。

错误格式

所有错误都遵循以下结构：

{
  "error": "description of what went wrong"
}

状态码

状态码	含义	出现场景
400	Bad Request	缺少或无效的参数、达到套餐限制或配额、功能需要更高套餐，或未获授权——所有验证失败都返回 400
402	Payment Required	保留给额度耗尽的情况。badges API 目前不扣减额度，因此实际上永远不会返回此状态码
404	Not Found	请求的资源不存在
500	Internal Server Error	服务器发生意外错误

没有 403 或 429：授权失败返回 400（“not authorized”），并且应用层没有速率限制。

常见错误与解决方法

缺少必需参数

{ "error": "missing required parameters: name, url, email" }

解决方法： 在请求体中包含所有必需参数。完整列表请查看对应端点的文档。

无效的电子邮件

{ "error": "invalid email" }

解决方法： 提供格式为 user@domain.com 的有效电子邮件地址。

无效的 URL

{ "error": "invalid URL" }

解决方法： 提供包含协议的完整 URL，例如 https://example.com.

名称过短

{ "error": "name must be at least 3 characters" }

解决方法： 使用更长的名称。颁发者名称至少需要 3 个字符，接收者名称至少需要 5 个字符。

颁发者未验证

{ "error": "issuer must be verified before creating badges" }

解决方法： 请先验证颁发者。检查颁发者邮箱中的验证链接，或使用 验证颁发者 端点。

达到凭证配额（400）

{ "error": "Your Free plan reached its credential limit (1200/1200) — your allowance renews on your plan anniversary, or upgrade to Starter" }

解决方法： 你已用完全年的凭证额度池（Free：1,200/年，Starter：12,000/年，Pro：120,000/年）。额度池在你账户的注册周年日重置，而不是按日历月边界重置。升级套餐可获得更高额度。参见 套餐与计费。

达到套餐限制（400）

{ "error": "Your Free plan reached its issuer limit (2/2) — delete an issuer or upgrade to Starter" }

徽章数量上限的格式相同：

{ "error": "badge limit reached (5/5 on the starter plan) — delete a badge or upgrade your plan" }

解决方法： 你已达到套餐对颁发者或徽章数量的上限。请删除不再使用的资源，或升级套餐。

资源存在依赖（400）

{ "error": "issuer has 3 badge(s) linked — delete the badges first" }

解决方法： 删除颁发者之前，请先删除与其关联的所有徽章。同样，删除徽章之前，请先删除该徽章下的所有凭证。

未获授权（400）

{ "error": "not authorized" }

授权失败属于验证错误，因此返回 400（而不是 401 或 403）。

解决方法： 你只能修改自己拥有的资源。请确认使用的是正确的 API 密钥。

分享文本中包含 HTML

{ "error": "HTML tags are not allowed" }

解决方法： 分享文本必须是纯文本。请从 text 参数中移除所有 HTML 标签。