錯誤

當 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 標籤。