エラー

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

解決方法： https://example.com のように、プロトコルを含む完全な URL を指定してください。

名前が短すぎる

{ "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 タグを削除してください。