Skip to main content

エラーレスポンスの形式

APIエラー時は、以下の形式でエラー情報が返されます。
エラーの種類によっては error.details に補足情報(バリデーションエラーの項目別メッセージ、retry_after、resource_type など)が含まれます。
次の応答は上記の error 形式ではなく、Laravel標準の形式です。Accept: application/json ヘッダーを付けたリクエストでは message だけを持つJSON(例: {"message": "Server Error"})、付けない場合はHTMLが返り、error.code は含まれません。
  • 存在しないパスへのリクエスト(404)
  • エンドポイントが対応していないHTTPメソッドでのリクエスト(405。PATCH 専用のエンドポイントへの PUT など)
  • イベント作成の internal_error 以外のサーバー内部エラー(500)

HTTPステータスコード

400 Bad Request

リクエストの前提条件が満たされていない場合に返されます。フィールドの入力値そのものの不備(必須・型・桁数など)は原則として400ではなく422になりますが、一部のAPIは必須・型の不備を400の validation_error(details なし)で返します(下表の validation_error の行)。
対処方法: error.message を確認し、設定状態や指定値を修正してから再実行してください。

401 Unauthorized

認証に失敗しました。レスポンスの error.code は常に unauthorized で、失敗の原因は message で示されます。
対処方法: Authorization: Bearer {api_key} ヘッダーが正しく付与されているか、管理画面でAPIキーが有効か確認してください。無効化されている場合は、管理画面のAPIキーの編集で「ステータス」を「有効」に戻すか、新しいキーを発行してください。アカウントが利用停止中の場合は、利用停止日の当日0:00からそのアカウントの全てのAPIキー(MCP接続キーを含む)が使えません。

403 Forbidden

リソースへのアクセス権限がありません。ライセンス共有されたファネル(共有範囲が「ライセンス登録者のみに共有」のファネルを受け取った側)のページ詳細取得とページ更新(PUT を含む)で返ります。同じファネルのページ一覧・ページ削除では返りません。
対処方法: ライセンス共有されたファネルのページコンテンツはAPIから取得・更新できません。対象のページがライセンス共有で受け取ったファネルのものでないか確認してください。

404 Not Found

指定されたリソースが見つかりません。message は資源ごとに異なります(「ページが見つかりません」「読者が見つかりません」「友だちが見つかりません」など)。
対処方法: URLに含まれるID(funnel_id, step_id, page_id等)が正しいか確認してください。存在しないパスへのリクエストの 404 は error 形式ではありません(エラーレスポンスの形式を参照)。

409 Conflict

リソースの状態が操作と競合しています。
対処方法: 対象リソースの現在の状態を取得して確認してください。同じリクエストをリトライしても解決しません。

422 Unprocessable Entity

リクエストパラメータのバリデーションに失敗しました。必須項目の未指定、型の誤り、桁数超過などフィールド単位の入力不備で発生します。error.code は validation_error で、error.details に項目ごとのエラー内容が含まれます。ただし、並び替えAPIでのIDの過不足・重複(会員サイト・コース・バンドル・商品・商品詳細・レッスンなど)、コース並び替えの course_group_id の重複、LINEテンプレートにメッセージが無いなど、項目に紐づかない検証では details が付かず message だけが返ります。details の各項目の値は通常はメッセージの配列ですが、会員サイト更新・コース更新の変更時だけ行う検証(色・文字サイズ・メニュー項目・開放設定など)では文字列です。
対処方法: error.details の各項目を確認し、該当するリクエストパラメータを修正してください。

validation_error 以外のコード

入力値は正しくても、契約内容による上限や配信の安全制御により処理できない場合は、422 で次のコードが返ります。いずれも error.details は付きません。
商品・会員サイト・コース・レッスンの契約内容による件数上限は、422 ではなく 400 bad_request で返ります。

429 Too Many Requests

リクエスト数や作成数の上限を超過しました。error.code で原因を判別できます。
X-RateLimit-Limit / X-RateLimit-Remaining は接続元IP単位の制限の値で、超過した分間・日間の上限や残数ではありません(認証を参照)。 リソース作成上限の場合は details.resource_type に対象のリソース種別が含まれます。
レート制限・リソース作成上限の仕組みと対象APIは認証を参照してください。

500 Internal Server Error

サーバー内部でエラーが発生しました。error 形式で internal_error が返るのはイベント作成だけで、リマインダ配信用のシナリオの雛形を解決できない場合に返り、イベントは作成されません。
それ以外のサーバー内部エラーは error 形式ではなく、Laravel標準の形式で返ります(Accept: application/json ヘッダーを付けたリクエストでは {"message": "Server Error"}、付けない場合はHTML)。error.code は含まれません。 対処方法: 時間をおいてリトライしてください。繰り返し発生する場合はサポートにお問い合わせください。

502 Bad Gateway

外部サービス(LINE API)への送信に失敗しました。error.code は external_service_error で、details.http_status にLINE APIのHTTPステータス、details.line_error にLINE APIの応答本文が含まれます。LINE 1対1チャット送信とLINE友だちリッチメニュー切替で発生します。
対処方法: details.line_error の内容を確認してください。LINE側の一時的な障害の場合は時間をおいてリトライしてください。

バリデーションエラーの詳細

要素構造エラー

elements方式のページでは、要素の階層ルールに違反するとバリデーションエラーになります。
正しい構造
誤った構造(エラーになる)
上記の誤った例では、elements直下にtext要素を直接配置しているためエラーになります。必ず section > row > col の階層を経由してください。

content_type変更不可

ページ作成後に content_type を変更することはできません。elements で作成したページを raw_html に変更(またはその逆)しようとすると400エラーになります。
異なるcontent_typeのページが必要な場合は、新しいページを作成してください。

ページ更新は部分更新

ページ更新APIは部分更新です。変更したいフィールドだけを送信すれば、未指定のフィールドは既存の値が維持されます(nullに上書きされることはありません)。
elements / popup_elements は指定しない場合は既存の要素が維持されます。指定した場合は配列全体で既存の要素と同期されます。
  • element_id を付けた要素: 送った項目だけ更新(送らなかった項目は既存の値を維持)
  • element_id の無い要素: 新規追加
  • 配列に含めなかった既存の要素: 削除
  • children キーを省略した要素: 既存の子要素を維持(section / row / col / form に空配列 children: [] を送ると 422)

リトライ戦略

APIエラー時の推奨リトライ戦略です。

429 Too Many Requests

error.code と details.retry_after の有無で待機時間を決めます。

5xx サーバーエラー

指数バックオフでリトライします。 最大5回程度のリトライを推奨します。それでも解決しない場合はサポートにお問い合わせください。502 external_service_error はLINE API側の応答に起因するため、details.line_error の内容を確認してからリトライしてください。

リトライ不要なエラー

以下のエラーはリクエスト内容の修正が必要であり、同じリクエストをリトライしても解決しません。
  • 400 - リクエストパラメータや設定状態を修正
  • 401 - APIキーを確認・再設定
  • 403 - リソースの権限を確認
  • 404 - リソースIDを確認
  • 409 - リソースの状態を確認
  • 422 - 入力内容を修正(plan_limit_exceeded などは契約内容・設定の見直しが必要)
エラー発生時の調査には、レスポンスボディの error.code と error.message をログに記録しておくことを推奨します。