錯誤

當 API 請求失敗時,badges.ninja 會回傳含適當 HTTP 狀態碼的 JSON 錯誤回應。

錯誤格式

所有錯誤皆遵循以下結構:

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

狀態碼

代碼	意義	何時發生
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/mo、Starter: 1,000/mo、Pro: 10,000/mo)。請等待下次重置或升級方案。請見 方案與計費。

已達方案限制

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

解法: 你已達方案的頒發者、徽章或 API 金鑰上限。請刪除未使用的資源或升級方案。

區塊鏈需 Pro 方案

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

解法: blockchain 參數僅於 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" }

解法: 分享文案必須是純文字。請自 text 參數移除所有 HTML 標籤。