错误

当 API 请求失败时,badges.ninja 会以合适的 HTTP 状态码返回一个 JSON 错误响应。

错误格式

所有错误遵循如下结构:

{
  "error": "出错原因描述"
}

状态码

代码	含义	出现时机
400	Bad Request	参数缺失或无效、达到套餐上限或配额、功能需要更高套餐,或未授权 — 所有校验失败都返回 400
402	Payment Required	保留给额度耗尽的情况。徽章 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": "monthly award quota reached (100/100 on the free plan) — wait for the 1st of next month or upgrade your plan" }

解决办法: 你已用完当前日历月内套餐内含的全部颁发(Free:100/月,Starter:1,000/月,Pro:10,000/月)。计数在每月 1 号 UTC 时间 00:00 重置;升级套餐可获得更高额度。参见 套餐与计费。

套餐上限已到(400)

{ "error": "issuer limit reached (1/1 on the free plan) — delete an issuer or upgrade your plan" }

徽章上限使用相同的结构:

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

解决办法: 已达到套餐在颁发者或徽章方面的上限。删除闲置资源或升级套餐。

区块链需要 Pro(400)

{ "error": "blockchain verification requires the Pro plan" }

解决办法: blockchain 参数仅 Pro 套餐可用。升级到 Pro 以启用它。

不支持的区块链

{ "error": "unsupported blockchain, only 'matchain' is supported" }

解决办法: 目前 matchain 是唯一受支持的区块链参数值。

资源存在依赖(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" }

解决办法: 分享文案必须为纯文本。从文本参数中移除所有 HTML 标签。