エラーコードと対処方法

Keelson で発生する主なエラーと、その確認方法・対処方法をまとめています。CLI のエラーに加え、コンソールで確認できるデプロイの失敗や、公開したアプリへのアクセス時のエラーも扱います。

CLI のエラーでは code と message、対処の案内がある場合は hint を確認してください。CLI や API でデプロイの失敗を確認する場合は、failure_code と failure_hint を確認します。案内が表示されている場合は、個別の状況に応じた内容なので、このページより優先してください。AI エージェントに調査や修正を依頼するときも、これらの情報を渡すと役立ちます。

このページは全コードを網羅していません。掲載のないコードが出た場合も、表示されたメッセージや対処の案内を確認してください。

エラーの確認方法

操作した場所によって、エラーを確認する画面や応答の形式が異なります。

確認する場所	確認方法・応答の形式
コンソール	アプリの概要やデプロイ履歴で、失敗したデプロイの理由とログを確認
CLI	ターミナルのエラーメッセージを確認。`--json` を付けると、標準出力の `error` に `code`、`message`、`hint`、`retryable` などが入る
デプロイの失敗(`keelson status` / `keelson diagnose`)	`failure_code` と `failure_hint` を確認
Keelson API	通常は `detail` にメッセージ。入力検証エラーでは `detail` が配列になる場合もある。承認が必要な操作、スナップショット、入力検証、管理権限などに関する一部のエラーでは、`error` に `code`、`message`、`hint` などが入る
公開したアプリへのアクセス拒否(ゲートウェイ)	ブラウザには案内画面。fetch / XHR には `{"detail":"ip-restricted"}` などの JSON。`X-Keelson-Auth-Error` ヘッダーで拒否の理由を確認できる
稼働枠不足・停止中(ゲートウェイ)	HTTP 503。`x-keelson-platform-error` ヘッダーに `capacity-full` / `app-suspended`。稼働枠不足では `X-Keelson-Error-Code: CAPACITY_FULL` も返る
存在しない URL・停止中・予約パスへのアクセス(エッジ)	HTTP 404 / 410 / 503 / 403。ブラウザには案内画面、API 等には平文を返す。一部の予約パスはブラウザにも平文を返す。理由は `x-keelson-platform-error` ヘッダーで確認する。ゲートウェイに届かないため `X-Keelson-Auth-Error` は付かない
Files / Media の配信	`x-keelson-error` ヘッダーで理由を確認。一部のコードでは `error`、`hint`、`doc` を含む JSON も返る

CLI の --json で返るエラーの例です。

{
  "error": {
    "code": "not_logged_in",
    "message": "Not logged in.",
    "hint": "Run `keelson login` or set KEELSON_TOKEN, then retry the command.",
    "retryable": false
  }
}

retryable は、同じ操作を再試行すると成功する可能性があるかを示します。HTTP ステータスだけでは判断できません。同じ 503 でも false の場合があり、ビルドの 429 にはトライアルの累積上限のように待っても解除されないものがあります。

デプロイ前のチェック(CLI)

アップロード前のチェック結果です。keelson deploy --check でも確認できます。エラーがあるとデプロイは中止されます。警告だけの場合は続行できます。

依存マニフェストとは、使用するライブラリを宣言するファイル(go.mod、requirements.txt、package.json など)です。Go では外部ライブラリを使わなくても go.mod が必要です。Python と Node.js では、依存マニフェストがなくても警告にとどまります。

コード	原因	対処
`missing_dependency_manifest`	選択したランタイムの依存マニフェストがない	Go ではプロジェクトルートに `go.mod` を置く。Python または Node.js で外部ライブラリを使う場合は、その依存関係を宣言するファイルを置く
`command_installs_dependencies`	`command` に `pip install` / `npm install` / `go build` がある	削除し、起動コマンドだけにする
`runtime_command_mismatch`	`runtime` と `command` の言語が合わない(例: `python-slim` で `node`)	どちらかを直す
`assets_dir_empty`	`assets.dir` が無い、空、またはパスの大文字小文字が違う	ビルドを実行する。パスを確認する
`assets_fallback_missing`	`assets.fallback` のファイルが `assets.dir` にない	ビルド出力を確認する
`db_wiring_fail`(警告)	`db.mode` とコードの DB 接続が食い違う(本番の接続先が `KEELSON_DB_URL` を読んでいない、ローカル開発用の `file:` フォールバックが本番経路に残っている、宣言との不一致など複数の規則がある。`file:local.db` を環境変数未設定時のフォールバックとして持つこと自体は問題ない)	表示された `hint` に従う。多くは `KEELSON_DB_URL` を読む libSQL クライアントに直す
`file_wiring_fail`(警告)	状態ファイルやアップロードをローカルディスクに書いている	Files / Media SDK に置き換える
`icon.path`	`icon` のファイルが無い、読めない、シンボリックリンク、またはアップロードから除外される	アップロードされる場所に画像を置き、`keelson.yaml` からの相対パスで `icon` を書く。icon を参照
`icon.format` / `icon.size` / `icon.dimensions` / `icon.corrupt`	`icon` の画像が PNG・JPEG・WebP でない、256KB を超える、縦横が 32〜2048 ピクセルの外、またはヘッダーが読めない	条件に合う PNG・JPEG・WebP で書き出し直す

keelson.yaml とアップロード内容の検証

次のエラーがあるとデプロイできません。

コード	原因	対処
`invalid_keelson_config`	YAML が不正、`db.mode` が `libsql` / `none` 以外、`db.migrate` を `none` と併用、`KEELSON_` で始まる env、`/__keelson` 配下のパス、不明な `runtime`、cron が 10 本超、など	`message` の内容を直す
`config_missing_field`	必須フィールドがない(`slug`、`runtime`、`db` など。静的サイトでは `type` と `assets` も)	追加する
`env_value_not_string`	`env` の値が文字列でない、YAML が曖昧に解釈するキー、キーの重複、merge key(`<<`)	値は引用符かブロック文字列にする。曖昧なキー(`on` / `yes` / 数字など)は引用符で囲む。重複は削除する。merge key は展開して書く。重複と merge key は引用符で囲んでも拒否される
`description_too_long`	`description` が 300 文字超	短くする
`workers_not_supported`	`workers:` がある	削除する。リクエストを受けて走らせる処理は `tasks`、時刻で動く処理は `crons` で書く
`DB_DATABASES_REMOVED`	`databases:` がある	削除する。永続データは `db.mode: libsql`
`SQLITE_LOCAL_SQLITE_INVALID_PATH`	`db.local_sqlite.paths` が `/tmp/` の外	`/tmp/` か `:memory:` にする
`CRON_TIMEOUT_EXCEEDS_STANDARD_LIMIT`	`crons[].timeout` が 600 秒超	600 秒以内にするか、処理を分割する
`plan_cron_limit` / `plan_cron_min_interval` / `plan_schedule_timeout`	cron の本数・実行間隔・`timeout` がプランの制限に合わない	本数を減らす、実行間隔を長くする、`timeout` を短くする。または必要な条件を満たすプランに変更する
`tasks_require_command_or_crons`	`tasks` があるのに `command` も `crons` も無く、タスクを投入するコードが無い	タスクを投入する Web アプリの `command`、または `crons` のジョブを追加する
`task_name_conflicts_with_cron`	`tasks[].name` が `crons[].name` と同じ(前後の空白を除いて小文字化した後で比べる)	タスクかジョブの名前を変える
`TASK_TIMEOUT_EXCEEDS_STANDARD_LIMIT`	`tasks[].timeout` が 600 秒超	600 秒以内にするか、処理を小さなタスクに分ける
`plan_task_timeout`	明示した `tasks[].timeout` がプランの 1 回の実行時間の上限を超える	`timeout` を短くするか、上限の大きいプランに変更する。`timeout` を省略した場合は拒否されず、プランの上限に切り下げられる
`ARTIFACT_SQLITE_FILE_DRIVER`	ファイル SQLite クライアント(`sqlite3`、`better-sqlite3` など)が検出された	libSQL クライアントへ移行。一時用途なら `db.local_sqlite` で宣言

ビルド出力の直下に __keelson ディレクトリがあるとビルドが失敗します。このときの failure_code は deploy.build.failed で、ビルドログに reserved_path_conflict が出ます。ディレクトリ名を変えてください。

アップロード内容に関する警告

次のコードは警告であり、これだけでデプロイが失敗することはありません。処理の目的に応じて対応してください。

コード	原因	対処
`ARTIFACT_EXEC_NODE_CRON` / `ARTIFACT_EXEC_APSCHEDULER`	アプリのプロセス内で定期処理を登録している	アプリがスリープすると実行されないため、定期処理を独立したコマンドに切り出し、`keelson.yaml` の `crons` に定義する
`ARTIFACT_EXEC_BACKGROUND_TASKS`	レスポンスを返した後に実行する処理がある	短い外部呼び出しや、リクエストの成功に必要な処理は、レスポンスを返す前に `await` して完了を待つ。レスポンスの後に続ける処理は `tasks` に宣言して SDK で投入する（バックグラウンドタスク）
`ARTIFACT_EXEC_SET_INTERVAL`	サーバー側のコードで `setInterval` を使っている	実行が抜けても問題のないキャッシュ更新などは変更不要。継続的な定期実行が必要な処理は `crons` に移す

デプロイの失敗

コンソールのアプリ概要・デプロイ履歴で、失敗の理由とログを確認できます。CLI の keelson status / keelson diagnose や API では、失敗コードを failure_code、対処の案内を failure_hint で確認します。デプロイ開始時に操作を受け付けられなかった場合のコードも、下表に記載しています。

コード	原因	対処
`deploy.config.invalid`	`keelson.yaml` の内容が不正	指摘されたキーを直して再デプロイ
`deploy.config.secret_missing`	`secrets.required` で宣言したシークレットが未設定	`keelson secrets set <KEY>`(値は標準入力)で全て設定してから再デプロイ
`deploy.artifact.invalid`	アップロードしたアーカイブの検証に失敗した(必要なロックファイルの不足など)	エラーメッセージで指摘されたファイルやコードを直す
`deploy.artifact.assets_invalid`	`assets.dir` / `assets.fallback` で宣言したファイルがアップロードに含まれていない	手元でビルドしてから再デプロイ
`deploy.build.failed`	ビルド失敗(依存の解決失敗、ビルドスクリプトのエラー、予約パスの衝突)	`keelson logs deploy <deploy_id>` でビルド出力の末尾を見る
`deploy.build.timed_out`	ビルドが制限時間内に終わらなかった	不要な依存を減らす、重い前処理をビルドの外に出す
`deploy.build.image_too_large`	イメージが大きすぎる	不要な依存やファイルを減らす
`deploy.runtime.start_failed`	アプリが起動中に終了、またはコンテナが起動状態にならなかった	`keelson logs deploy <deploy_id>` で保存済みのアプリの起動ログを読み、`PORT` と `0.0.0.0` を確認
`deploy.runtime.health_check_failed`	起動・ヘルス検証の制限時間内に、`/`(もしくは `health.path`)から期待する応答(2xx / 3xx / 404)を得られなかった。アプリが起動中に終了した場合や、401 / 403 / 5xx を返し続ける場合を含む	`keelson logs deploy <deploy_id>` で保存済みのアプリの起動ログを読み、待ち受けポートと `health.path` を確認
`deploy.runtime.migration_failed`	`db.migrate` が 0 以外で終了。旧リビジョンが配信を継続	マイグレーションを直して再デプロイ。途中まで適用された DB の変更は自動では戻らない
`deploy.verify.failed`	`verify` のパスが取得できない、または JS / CSS の Content-Type が不一致	パスとビルド出力を確認。詳細は `failure_logs` の `verification_*` コードに出る
`deploy.plan.limit_exceeded`	プランの上限を超えている	`failure_hint` で対象の上限を確認し、設定や使用量を上限内に収める。または必要な上限のあるプランに変更する
`deploy.plan.cron_count_exceeded`	cron の本数がプラン上限を超えている	cron の本数を減らすか、より多く登録できるプランに変更する
`deploy.plan.cron_interval_too_short`	cron の間隔がプランの最小間隔より短い	実行間隔を長くするか、より短い間隔で実行できるプランに変更する
`deploy.plan.schedule_timeout_exceeded`	明示した `crons[].timeout` がプラン上限を超えている	`timeout` を短くするか、必要な実行時間に対応したプランに変更する
`deploy.app.suspended`	アプリまたはワークスペースが Keelson 側の制限措置を受けている	サポートへ連絡する。利用者や管理者による再開では解除されない
`deploy.app.operation_in_progress`	このアプリで別の操作が進行中だったため、デプロイを開始できなかった	別の操作が完了してから再デプロイ
`deploy.platform.temporarily_unavailable`	一時的な障害	待ってから再試行する。追加で 3 回まで。それでも失敗するなら `deploy_id` を添えてサポートへ
`deploy.platform.error`	プラットフォーム側のエラー	再試行しても直らない。`deploy_id` を添えてサポートへ
`deploy.cancelled`	デプロイが取り消された	必要なら再デプロイ
`deploy_in_progress`(409)	別のデプロイまたはアプリ操作が進行中	進行中の操作が完了してから同じコマンドを再実行
`build_rate_limit_exceeded` / `build_guardrail_exceeded`(429)	ビルド回数・ビルド時間・同時実行・連続失敗の上限	メッセージが解除条件を示す。連続失敗は原因を直して記載の時刻を待つ。トライアルのビルド枠は累積で、待っても解除されないので、その場合はプランを変更する
`saved_config_unsupported`(409)	再デプロイ / ロールバック対象の `keelson.yaml` が現在のスキーマに合わない	直して通常のデプロイをする

定期実行ジョブの失敗・スキップ

keelson crons runs list --json の executions[].failure_code で確認できます。失敗の調査には keelson logs cron で実行ログも確認してください。

cron.failed.* は開始したジョブの失敗、dispatch_failed はジョブを起動できなかったことを示します。cron.skipped.* は、条件を満たさないため予定されていた実行をスキップしたことを示します。

コード	意味
`cron.failed.command_failed`	コマンドが 0 以外で終了した
`cron.failed.timed_out`	`timeout` を超えた
`cron.failed.terminated_no_callback`	実行が終了したが結果が報告されなかった
`dispatch_failed`	実行の起動に失敗した
`cron.skipped.schedule_disabled`	ジョブが無効化されている
`cron.skipped.quota_exceeded`	プランの実行枠を超えた
`cron.skipped.due_to_lock` / `cron.skipped.lease_held`	前回の実行がまだ終わっていない
`cron.skipped.missed_run`	予定時刻を過ぎたため実行をスキップした
`cron.skipped.app_suspended`	アプリが停止中
`cron.skipped.plan_downgrade`	プラン変更で実行できなくなった

バックグラウンドタスクのエラー

アプリが enqueue や get を呼んだときに、Tasks SDK が返すエラーです。SDK のエラーは言語ごとに 1 種類(Python と Node.js は TasksError、Go は *tasks.Error)で、code・status・message を持ちます。分岐は code で行い、message の文言に頼らないでください。使い方はバックグラウンドタスクを参照してください。

コード	意味	出る場面	対処
`TASK_INVALID_REQUEST`	タスク名が空、`idempotency_key` が 1〜128 文字の印字可能 ASCII でない、`payload` を JSON にできない、などの不正な要求	`enqueue`(本番・手元)	引数を直す。同じ呼び出しを繰り返しても通らない
`TASK_NOT_DECLARED`	タスク名が、現在デプロイされている `tasks` に無い(手元では `keelson.yaml` に無い)。`tasks` から外した名前を含む	`enqueue`(本番・手元)	`tasks` に宣言してデプロイするか、名前を直す
`TASK_NOT_FOUND`	`task_id` が存在しないか、別のアプリのタスク。手元の `get` は同じプロセスで投入したタスクしか知らない	`get`(本番・手元)	アプリが保存した `task_id` を確かめる
`TASKS_UNAVAILABLE`	タスクの受付が閉じている、またはアプリがサスペンド・隔離・削除中。繰り返しても通らない	`enqueue`(本番だけ)	コンソールでアプリの状態を確認する。Keelson が制限したアプリはサポートに連絡する
`TASK_PAYLOAD_TOO_LARGE`	投入要求の body(`payload` と `idempotency_key` を JSON にしたもの)が 65,536 bytes を超える	`enqueue`(本番・手元)	大きな入力はデータベースかファイル保存の SDK に置き、その ID を `payload` で渡す
`TASK_BACKLOG_LIMIT_EXCEEDED`	アプリの未処理(`queued`)のタスクが 1,000 件に達している	`enqueue`(本番だけ)	未処理のタスクが減るのを待つか、投入の頻度を下げる。投入済みのタスクには影響しない
`TASK_MONTHLY_QUOTA_EXCEEDED`	ワークスペースの月間枠「バックグラウンド実行」で、1 回目の試行の分を確保できない	`enqueue`(本番だけ)	確保済みの枠が返されたとき・プランを上げたとき・翌 UTC 月初のいずれかで通るようになる。同じ月の中でも通ることがあるので、翌月まで止まると決め打ちしない。SDK は自動で再試行しない
`TASKS_UNAVAILABLE_TRANSIENT`	一時的な障害(エラー本文の無い 502 / 503 / 504、接続の失敗、1 回あたり 15 秒の時間切れ)	`enqueue`・`get`(本番だけ)	SDK が合計 3 回まで試す。`enqueue` は `idempotency_key` があるときだけ再試行するので、重複を作らないようキーを付ける
`TASKS_UNAUTHORIZED`	runtime API が ID トークンを受け付けなかった(401)	`enqueue`・`get`(本番だけ)	続く場合はサポートに連絡する
`TASKS_FORBIDDEN`	Cloud Run が呼び出しを拒否した(403)。`tasks` を宣言した最初のデプロイの直後は、権限の反映に数分かかることがある	`enqueue`・`get`(本番だけ)	最初のデプロイから数分待って試し直す。続く場合はサポートに連絡する
`TASKS_SERVER_ERROR`	エラー本文の無い、その他の 5xx	`enqueue`・`get`(本番だけ)	時間をおいて試し直す。`enqueue` を試し直すときは `idempotency_key` を付ける
`TASKS_HTTP_ERROR`	エラー本文の無い、その他の失敗の応答	`enqueue`・`get`(本番だけ)	続く場合はサポートに連絡する
`TASKS_UNEXPECTED_RESPONSE`	成功の応答が決められた形でなかった	`enqueue`・`get`(本番だけ)	SDK を更新する。続く場合はサポートに連絡する
`TASKS_IDENTITY_TOKEN_ERROR`	メタデータサーバーから ID トークンを取れなかった	`enqueue`・`get`(本番だけ)	続く場合はサポートに連絡する
`TASKS_NOT_CONFIGURED`	SDK が本番と手元のどちらで動かすかを決められなかった(`KEELSON_MODE` が不明な値、`KEELSON_MODE=keelson` なのに `KEELSON_TASKS_BASE_URL` か `KEELSON_APP_ID` が無い、など)	`enqueue`・`get`	本番では `KEELSON_MODE` などの `KEELSON_` 変数を上書きしない。手元では `KEELSON_MODE=local` にするか Keelson の変数を外す。環境変数を参照
`TASKS_LOCAL_CLI_NOT_FOUND`	`PATH` に `keelson` が無い	`enqueue`(手元だけ)	`https://keelson.dev/install.sh` で CLI を入れる
`TASKS_LOCAL_CLI_FAILED`	CLI がタスクを実行できなかった(`keelson dev task run` の無い古い CLI、中断など)	`enqueue`(手元だけ)	`keelson upgrade` を実行する。`keelson dev task run <name> --payload '<JSON>'` で直接エラーを確かめる

コマンドが 0 以外で終わった・時間切れになったことは enqueue のエラーではありません。タスクは failed で終わり、get の last_failure_code に理由が入ります。

タスクの失敗理由(`last_failure_code`)

get は、failed のタスクと、再試行を待っているタスクに last_failure_code を返します。最後の試行の標準エラーは、コンソールのアプリ画面の「バックグラウンドタスク」タブで確認できます。

値	意味	試行回数に数えるか	再試行
`exit_nonzero`	コマンドが 0 以外の終了コードで終わった	数える	試行回数が残っていればする
`timed_out`	試行が `timeout` を超え、Keelson がコマンドを打ち切った	数える	試行回数が残っていればする
`no_completion`	結果の連絡が無いまま期限を過ぎた	数える	試行回数が残っていればする
`delivery_failed`	試行を 1 時間以内に開始できなかった	数えない	しない
`manifest_unresolvable`	待っている間にデプロイが 2 回以上重なり、投入時の宣言を使えなくなった	数えない	しない
`quota_exhausted`	再試行、または月をまたいで開始する試行で、月間枠「バックグラウンド実行」を確保できなかった	数えない	しない

手動の再実行はありません。もう一度実行するには、アプリから投入し直してください。

バックアップと復元

keelson snapshots ... のエラーです。snapshot_export_ で始まるコードは、snapshots export で発生します。

コード	意味	対処
`snapshot_plan_not_included`	手動スナップショットがプランに含まれない（現在は全プランで利用できるため、通常は発生しない）	サポートに連絡する
`snapshot_no_managed_db`	Managed SQLite を使っていない	`db.mode: libsql` でデプロイし、DB を作成する
`snapshot_db_name_invalid` / `snapshot_db_name_unknown`	DB 名が不正、または存在しない	`hint` に出る名前を使う
`snapshot_already_running` / `snapshot_export_already_running`	前の処理が実行中	終わってから再試行
`snapshot_rate_limited` / `snapshot_export_rate_limited`	回数上限	`hint` の時刻まで待つ
`snapshot_export_invalid_timestamp`	復元可能な範囲の外の時刻	範囲内の時刻を指定する
`snapshot_app_deleting` / `snapshot_export_app_deleting`	アプリが削除中	—
`snapshot_launch_failed` / `snapshot_export_launch_failed`	起動に失敗	再試行。続くならサポートへ
`snapshot_disabled` / `snapshot_storage_unconfigured`(`snapshot_export_` で始まるコードも同様)	機能が無効、または保存先が未設定	サポートへ連絡する
`snapshot_not_ready`	まだダウンロードできない(`X-Keelson-Error-Code` ヘッダー)	完了を待つ

CLI のエラー

コマンドの実行時に表示される主なコードです。

コード	意味	対処
`not_logged_in`	未ログイン	`keelson login`
`multiple_workspaces` / `workspace_ambiguous` / `workspace_not_found`	ワークスペースを特定できない	`--workspace <slug>` で指定する。`keelson workspaces list --query <検索文字列>` で検索できる
`no_workspaces`	利用できるワークスペースがない	コンソールでワークスペースを作成する
`app_not_found`	アプリが見つからない	`slug` を確認。新規なら `--new`
`app_manage_required`	アプリは存在するが、管理権限がない	現在の管理者に、管理権限を持つグループへ自分を追加してもらう。ワークスペースの OWNER / ADMIN なら `keelson groups members add <グループ> <メール>` で自分を追加する
`app_deleting`	削除中のアプリ	完了を待つ
`forbidden`	権限がない。`CONSOLE_ONLY_OPERATION` ならコンソール限定の操作	ロール・アプリ権限を確認
`confirmation_expired` / `confirmation_rejected`	承認の期限切れ(削除・SQL・復元は 15 分、`preview` / `app curl` は 30 分)/ 却下	コマンドをやり直す
`deploy_failed`	デプロイ失敗	`keelson diagnose <deploy_id>`
`sql_failed`	`db apply` の SQL エラー。ロールバック済み	SQL を直す
`usage`(`access set`。API の 409 `detail.reason` が `last_manage_binding_removed` / `no_effective_manager` / `self_lockout`)	管理グループが空になる、有効な管理者がいなくなる、自分の権限が失われる	管理グループを残す。`--allow-self-lockout` で解除できるのは自分が外れる場合だけで、管理グループや有効な管理者がゼロになる変更は解除できない
`transient`	一時的なネットワークエラー	`--retry 3` のように再試行回数を指定して実行

旧コードとの互換性: ワークスペースに関する一部のコードでは、旧 tenant 名のコードを互換用の error.aliases に含めます。旧コードの撤去時期は未定です。

ブラウザでの承認が必要な場合

confirmation_required は、操作を進めるためにブラウザでの承認が必要なことを示します。表示された URL を開いて承認してください。

削除・SQL・復元は承認と同時に実行されるため、コマンドの再実行は不要です。
preview / app curl は、承認後に --confirmation <id> を付けて同じコマンドを再実行してください。

AI エージェント向け Skill の更新案内

meta.skill_outdated または keelson doctor の skill_outdated 警告は、インストール済みの Skill が CLI より古いことを示します。この警告だけでコマンドが失敗することはありません。keelson install-agent --yes で更新してください。

公開したアプリにアクセスしたときのエラー

以下は公開したアプリを開いたときの案内です。コンソール自体のエラー画面ではありません。

表示	状態	対処
ログイン画面	未ログイン	ワークスペースに登録されたアカウントでログイン
「このアプリへのアクセス権限がありません」(403)	メンバーでない、ブロック済み、アプリの閲覧権限がない	管理者にメンバー登録・権限を依頼
「このアプリは、許可されたアクセス元からのみ利用できます」(403)	IP 制御で拒否。画面に送信元 IP が表示される	管理者に、表示された IP アドレスを許可するか確認してもらう
「アプリの稼働枠が空いていないため現状アプリが起動できません。」(503)	同時に使えるアプリ数の上限	通常は、枠を使っている別のアプリへのアクセスが約 5 分途絶えると空く。枠が空かない場合は、管理者にアプリの停止やプラン変更を相談する
「アプリを起動しています」	スリープからの起動中	自動で画面が切り替わるまで待つ
「このアプリは停止されています」(503)	管理者による停止、または Keelson 側の制限措置	管理者に停止理由を確認する。管理者が再開できない場合はサポートへ連絡する
「アプリが見つかりません」(404)	URL に対応するアプリが見つからない。URL の誤り、アプリの停止・削除、作成直後の公開待ちなど	URL とアプリの状態を確認する。作成直後なら少し待つ
「この URL は利用できません」(410)	公開 URL が変更された(旧 URL は 30 日間予約)	管理者に現在の URL を確認する

API や XHR から同じ状況になると、ゲートウェイの拒否では JSON の detail と X-Keelson-Auth-Error ヘッダーに理由(ip-restricted、app-view-denied など)が入ります。稼働枠不足と停止中は x-keelson-platform-error ヘッダー(capacity-full、app-suspended)です。

アプリへのリクエストで返る HTTP エラー

次のエラーは、アプリへのリクエストや接続で発生します。特に WebSocket 接続の 501 は、そのままブラウザの案内画面として表示されるものではなく、利用者への表示はアプリ側のエラー処理によって異なります。

HTTP ステータス	原因	アプリ開発者の対処
504	アプリが 120 秒以内に応答ヘッダーを返し始めなかった。ストリーミング全体の時間制限ではない	応答までの処理時間を短くする。時刻や間隔を指定して実行できる定期処理なら `crons` に移す
501	Keelson が WebSocket に対応していない	SSE やポーリングを使う

外部連携(アプリトークン / Webhook)

ゲートウェイで認証・認可が拒否された場合は、詳しい理由が X-Keelson-Auth-Error ヘッダーで返ります。IP 許可範囲による拒否でも、互換性のため JSON の detail は machine-forbidden または webhook-forbidden のままです。

ゲートウェイでは、アプリの経路が見つからない場合と、トークンが別のアプリのものである場合を、machine-forbidden / webhook-forbidden にまとめて返します。一方、ゲートウェイに届く前にエッジで URL の経路が見つからない場合は 404 になります。

`X-Keelson-Auth-Error`	原因
`invalid-app-token`	トークンが無効、または失効済み
`machine-scope-denied`	トークンに `api` スコープがない
`machine-endpoint-denied`	`auth.endpoints` で宣言されていないパス・メソッド
`machine-forbidden` / `webhook-forbidden`	ゲートウェイでアプリの経路が見つからない、またはトークンが別のアプリのもの
`machine-ip-not-allowed`	アプリトークンの許可 IP の外から呼ばれた
`invalid-webhook-secret`	Webhook シークレットが一致しない
`webhook-scope-denied`	トークンに `webhook` スコープがない
`webhook-ip-not-allowed`	Webhook トークンの許可 IP の外から呼ばれた

/api/webhooks/email などプラットフォーム予約のパスへの Webhook は、ゲートウェイより手前のエッジが 403 の平文で拒否します。このときのヘッダーは X-Keelson-Auth-Error ではなく x-keelson-platform-error: auth-webhook-endpoint-blocked です。