API エラー

API はエラーを標準の HTTP ステータスコードと統一されたレスポンスボディで通知します。成功したレスポンスはラッパーなしで直接データを返します。

エラーフォーマット

エラー時のレスポンスボディは、人が読めるメッセージを含む error フィールドを持つ JSON オブジェクトです:

{"error":"reaction not found"}

まず HTTP ステータスコードを基準に判断し、error のテキストはログやユーザーへのヒントに使用してください。

ステータスコード

  • 200 OK — リクエスト成功、ボディにデータあり。
  • 201 Created — 新しいリソースが作成されました（一部の POST エンドポイント）。
  • 204 No Content — ボディなしで成功（一部の削除操作）。
  • 400 Bad Request — リクエストボディまたはパラメータが不正です。
  • 401 Unauthorized — トークンがないか、無効または期限切れ。あるいはそのルートは個人トークンではアクセスできません。
  • 402 Payment Required — アクションがプランまたはクォータの制限に達しました（例: 独自メディアストレージには premium が必要）。
  • 403 Forbidden — トークンにこのルートに必要なスコープがありません。
  • 404 Not Found — リソースが見つからないか、あなたのものではありません。
  • 409 Conflict — 状態の競合（例: ユニーク値の重複）。
  • 422 Unprocessable Entity — ボディの構文は正しいが、ドメインの検証に失敗しました。
  • 429 Too Many Requests — リクエスト制限を超過しました（レート制限 を参照）。
  • 500 Internal Server Error — サーバー内部エラー。しばらく待ってから再試行してください。

エラーの処理方法

2xx コードを成功とみなしてください。401/403 の場合はトークンとそのスコープを確認してください。4xx（429 を除く）ではリクエストを修正せずに再試行しないでください。429 と 5xx の場合は指数バックオフで再試行するのが適切です。

次のステップ