錯誤

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

錯誤格式

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

{
  "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": "monthly award quota reached (100/100 on the free plan) — wait for the 1st of next month or upgrade your plan" }

解法: 你已用盡當月方案所含的頒發額度(Free: 100/mo、Starter: 1,000/mo、Pro: 10,000/mo)。計數器於每月 1 日的 00:00 UTC 重置;升級方案可獲得更高額度。請見 方案與計費。

已達方案限制(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 方案可用。請升級以啟用。

不支援的區塊鏈

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

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