错误

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

错误格式

所有错误遵循如下结构:

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

状态码

代码	含义	出现时机
400	Bad Request	参数缺失或无效
402	Payment Required	月度颁发配额已满或该功能需要更高套餐
403	Forbidden	达到套餐上限(例如颁发者或徽章上限)
404	Not Found	请求的资源不存在
429	Too Many Requests	超出速率限制
500	Internal Server Error	服务器发生意外错误

常见错误与解决办法

缺少必填参数

{ "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" }

解决办法: 先验证颁发者。查看颁发者邮箱中的验证链接,或使用 验证颁发者 端点。

月度颁发配额已满

{ "error": "monthly award quota reached" }

解决办法: 你已用完本计费周期内套餐内含的全部颁发(Free:100/月,Starter:1,000/月,Pro:10,000/月)。等待下次重置或升级套餐。参见 套餐与计费。

套餐上限已到

{ "error": "issuer limit reached for your plan" }

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

区块链需要 Pro

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

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

不支持的区块链

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

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

资源存在依赖

{ "error": "issuer has badges and cannot be deleted" }

解决办法: 删除颁发者前先删除其下所有徽章。同理,删除徽章前先删除其下所有颁发记录。

未授权

{ "error": "not authorized" }

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

分享文案中含 HTML

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

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