🧰
【Supabase】Edge Functionsのステータスコードまとめ
はじめに
Supabase Edge Functionsが返すHTTPステータスコードの仕様をまとめた備忘録です。公式ドキュメントに基づき、エラーレスポンスを正しく理解し、デバッグやクライアント実装に役立てることを目的とします。
レスポンスは大きく正常系レスポンス、クライアントエラー、サーバーエラーの3つに分類されます。
正常系レスポンス (Success Responses)
2xx Success
関数が正常に実行され、有効なレスポンスを返したことを示します。これには、関数内で new Response() を使って明示的に返される200〜299の全てのステータスコードが含まれます。
3xx Redirect
関数が Response.redirect() APIを使用し、クライアントを別のURLへリダイレクトしたことを示します。認証フローやURL転送などで使用される正常な応答です。
クライアントエラー (Client Errors)
リクエスト自体に問題があることを示すエラーで、通常は関数の呼び出し方法を修正する必要があります。これらはSupabaseプラットフォームによって自動的に返されます。
401 Unauthorized
- 原因: JWT検証が有効な関数に対し、無効または存在しないJWTトークンでリクエストが行われた場合に発生します。
-
対処:
-
Authorizationヘッダーに有効なJWTトークンを渡しているか確認する。 - トークンの有効期限が切れていないか確認する。
- Webhookなどの公開エンドポイントでは、JWT検証を無効にすることを検討する。
-
404 Not Found
- 原因: リクエストされた関数が存在しない、またはURLパスが不正な場合に発生します。
-
対処:
- 関数名とプロジェクト
refがURLで正しいか確認する。 - 関数が正常にデプロイされているか確認する。
- 関数名とプロジェクト
405 Method Not Allowed
-
原因: サポートされていないHTTPメソッド（
GET,POST,PUT,PATCH,DELETE,OPTIONS以外）でリクエストされた場合に発生します。 - 対処: サポートされているいずれかのHTTPメソッドを使用するようにリクエストを修正する。
サーバーエラー (Server Errors)
関数の実行中またはプラットフォーム基盤で問題が発生したことを示します。
500 Internal Server Error
-
原因: (
WORKER_ERROR) 関数コード内で捕捉されなかった例外がスローされた場合に発生します。 -
主な要因:
- 非同期処理でのエラーハンドリング漏れ。
- 不正なJSONのパース。
- コード内の一般的なJavaScriptエラー。
-
対処: Edge Functionsのログを確認し、具体的なエラーを特定してコード内に適切なエラーハンドリング（例:
try/catch）を追加する。
503 Service Unavailable
-
原因: (
BOOT_ERROR) 関数の起動（ブート）に失敗した場合に発生します。 -
主な要因:
- 構文エラー。
-
importエラーや依存関係の欠如。 - 不正な関数設定。
-
対処: Edge Functionsのログを確認し、
supabase functions serveコマンドでローカル実行を試みて問題を特定・修正する。
504 Gateway Timeout
- 原因: 関数がリクエストのタイムアウト制限内に応答しなかった場合に発生します。
-
主な要因:
- 時間のかかるデータベースクエリ。
- 外部API呼び出しの遅延。
- 無限ループやブロッキング処理。
- 対処: 遅い処理を最適化するか、外部API呼び出しにタイムアウト処理を追加する。または、大きな処理をより小さなタスクに分割することを検討する。
546 Resource Limit (カスタムエラーコード)
-
原因: (
WORKER_LIMIT) 関数の実行がリソース上限（メモリ、CPU時間など）を超えたために停止された場合に発生します。 - 対処: Edge Functionsのログを確認して、どのリソースが上限を超えたかを特定し、コードを最適化する。
参考
Discussion