エラー

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

対処: 現時点で blockchain パラメータとして対応しているのは matchain のみです。

依存関係のあるリソース

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

対処: 発行者を削除する前に、その配下のすべてのバッジを削除してください。同様に、バッジを削除する前にその配下の授与をすべて削除してください。

権限なし

{ "error": "not authorized" }

対処: 自分が所有するリソースのみ編集できます。正しい API キーを使っているか確認してください。

共有テキストに HTML が含まれる

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

対処: 共有テキストはプレーンテキストである必要があります。テキストパラメータから HTML タグを取り除いてください。