エラーレスポンスの形式
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 を含む)で返ります。同じファネルのページ一覧・ページ削除では返りません。
404 Not Found
指定されたリソースが見つかりません。message は資源ごとに異なります(「ページが見つかりません」「読者が見つかりません」「友だちが見つかりません」など)。
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 に対象のリソース種別が含まれます。
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方式のページでは、要素の階層ルールに違反するとバリデーションエラーになります。正しい構造
誤った構造(エラーになる)
content_type変更不可
ページ作成後にcontent_type を変更することはできません。elements で作成したページを raw_html に変更(またはその逆)しようとすると400エラーになります。
ページ更新は部分更新
ページ更新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 をログに記録しておくことを推奨します。