API のエラーコードと対処方法

Square Cloud API への失敗したリクエストは、HTTP ステータスと、機械可読な code を含む JSON ボディを返します。このページでは、すべてのコードを分野別に一覧にしています。各エンドポイントのページにも、そのエンドポイントがよく返すコードが記載されています。

Blob Storage には独自のコード一覧があり、AI Gateway は小文字のコードを使う OpenAI のエラー形式で応答します。どちらもこのページでは扱いません。

エラーの形式

{
  "status": "error",
  "code": "APP_NOT_FOUND",
  "message": "Optional explanation for humans."
}

フィールド	説明
`status`	失敗時は常に `"error"` です。
`code`	`UPPER_SNAKE_CASE` のエラーコードです。このフィールドで分岐してください。
`message`	任意。人が読むための説明で、いつでも変わる可能性があります。人に表示するのはかまいませんが、解析はしないでください。

コードの一覧は今後も増えていきます。知らないコードは、一緒に返された HTTP ステータスの一般的な失敗として扱ってください。4xx ならリクエストを修正し、429 なら待ち、5xx なら後で再試行します。

再試行

API は Retry-After ヘッダーを送信しないため、判断はクライアント側に委ねられます。安全な方針は次のとおりです。

レスポンス	対処
`400`、`401`、`403`、`404`、`409`、`413`、`415`	同じリクエストを再試行しないでください。同じように失敗します。先に入力、認証情報、またはプランを修正してください。
`429`	次のリクエストまで待ってください。ループで再試行するとブロックされたままになります。レート制限を参照してください。
`503 UPLOAD_BUSY`、`503 ANALYTICS_BUSY`	少し待ってから、指数バックオフで再試行してください。
`503 DATABASE_UNAVAILABLE`	読み取りは数秒後に再試行してください。書き込みはすでに適用されている可能性があるため、繰り返す前にリソースを確認してください。
`500` とその他の `5xx`	バックオフを入れて 1、2 回再試行してください。失敗が続く場合はサービスステータスを確認してください。

202 SNAPSHOT_PROCESSING は互換性のためにエラーの形式を保っていますが、失敗ではありません。スナップショットはまだ生成中で、完了すると自動的に一覧に表示されます。再度リクエストしないでください。

レート制限

429 を返すコードは 2 つあり、意味が異なります。

RATE_LIMITED: アカウントまたは API キーのリクエスト枠で、60 秒ごとにカウントされ、プランによって決まります (プランごとの値を参照)。枠を超えると、API は最大 30 分間リクエストを拒否します。一部のエンドポイントは独自の制限でも RATE_LIMITED を返し、どのアカウントにも属さない API キーを送り続ける IP アドレスは短時間ブロックされます。
KEEP_CALM: 数秒に 1 回の再起動など、エンドポイント固有の制限です。少し待ってから再試行してください。各エンドポイントの制限はそのページに記載されています。

認証と権限

コード	HTTP	意味と対処
`ACCESS_DENIED`	401	API キーがない、誤っている、取り消されている、または期限切れです。あるいは、そのアカウントがもう存在しません。アカウントのセキュリティ設定でキーを確認し、ループで再試行しないでください。
`MISSING_SCOPE`	403	キーは有効ですが、このエンドポイントに必要なスコープがありません。スコープは編集できないため、そのスコープを持つキーを作成してください。スコープを参照してください。
`RESOURCE_NOT_ALLOWED`	403	キーがこのリソースを含まないアプリケーションとデータベースに制限されているか、エンドポイントがアカウント全体を対象とし、キーが制限されています。そのリソースを対象とするキーを使ってください。
`PERMISSION_DENIED`	403	workspace のロールでは、共有アプリケーションに対するこの操作が許可されていません。例えば `admin` ロールなしで `.env` を読み取る場合です。workspace のロールを参照してください。
`SCOPE_NOT_GRANTABLE`	403	制限付きの API キーが、自身の持つ以上のアクセス権を付与しようとしました。例えば `envs:write` のないキーで `admin` のメンバーを追加する場合です。そのロールのすべてのスコープを持つキーか、ダッシュボードを使ってください。
`UPGRADE_REQUIRED`	402 / 403	機能に上位のプランが必要です。データベース、カスタムドメイン、workspace には Standard 以上、ネットワークのログとパフォーマンスには Pro 以上、アカウントのスナップショットの一覧には有効なプラン (`402`) が必要です。可能な場合は `message` にプラン名が示されます。

リクエストの検証

コード	HTTP	意味と対処
`INVALID_JSON_BODY`	400	ボディが有効な JSON ではありません。`Content-Type: application/json` と正しい形式のボディを送信してください。
`INVALID_INPUT`	400	フィールドの検証に失敗しました。どのフィールドかは `message` に示されます。
`INVALID_ID`	400	必須の id (通常は `workspaceId`) がないか、形式が不正です。
`INVALID_CONTENT_TYPE`	415	アップロードとコミットには、`file` フィールドに zip を入れた `multipart/form-data` が必要です。
`PAYLOAD_TOO_LARGE`	413	ボディが、このエンドポイントが受け付けるサイズを超えています。
`ROUTE_NOT_FOUND`	404	パスまたは HTTP メソッドが誤っています。エンドポイントのページと照らし合わせてください。

クォータと接続数の制限

コード	HTTP	意味と対処
`RATE_LIMITED`	429	アカウントまたはキーのリクエスト枠、またはエンドポイント固有の制限に達しました。レート制限を参照してください。
`KEEP_CALM`	429	短時間にこのエンドポイントへのリクエストが多すぎます。少し待ってから再試行してください。
`DAILY_SNAPSHOTS_LIMIT_REACHED`	429	24 時間あたりの手動スナップショットのプラン枠を使い切りました。次の作成まで待つか、より大きな枠のためにアップグレードしてください。
`REALTIME_MAX_CONNECTIONS`	429	アカウントですでに 5 つのリアルタイム接続が開いています。先にいずれかを閉じてください。
`REALTIME_MAX_CONNECTIONS_APP`	429	アプリケーションで、全ユーザー合計ですでに 30 のリアルタイム接続が開いています。

アプリケーション

コード	HTTP	意味と対処
`APP_NOT_FOUND`	404	アプリケーションが存在しない、自分のものではない、または共有されている workspace のメンバーではありません。id を確認してください。workspace のルートでは、ボディに `appId` がない場合 `400` を返します。
`CONTAINER_ALREADY_STARTED`	409	アプリケーションまたはデータベースはすでに実行中です。成功として扱ってかまいません。
`CONTAINER_ALREADY_STOPPED`	409	アプリケーションまたはデータベースはすでに停止しています。成功として扱ってかまいません。
`CONTAINER_TEMPORARILY_SUSPENDED`	409	リソースは一時停止されています。理由はアカウントのメールを確認してください。
`CONTAINER_NOT_FOUND`	409	リソースのコンテナがサーバー上に見つかりませんでした。少し待って再試行し、解決しない場合はサポートに連絡してください。
`CONTAINER_INSUFFICIENT_DISK_SPACE`	409	起動に必要なディスク容量が足りません。不要なファイルを削除して再試行してください。
`CONTAINER_NETWORK_CONFLICT`	409	ネットワークまたはポートの競合により起動できませんでした。少し待って再試行してください。
`ACTION_FAILED`	409	デプロイ中など、別の理由で起動、停止、再起動が拒否されました。ステータスを確認して再試行してください。
`RESTORE_IN_PROGRESS`	403	このリソースでスナップショットの復元が実行中です。アプリケーションの削除や、データベースの起動、停止、削除は、復元が終わるまで待ってください。
`DELETE_FAILED`	404	リソースをホストするノードが削除を拒否しました。再試行してください。ファイルマネージャーでは、同じコードが `400` を返します。
`LOGS_UNAVAILABLE`	404	ログを読み取れませんでした。アプリケーションがオフライン、一度もデプロイされていない、またはノードが応答しませんでした。少し待って再試行してください。
`METRICS_NOT_SUPPORTED`	400	メトリクスは RAM が 512 MB 以上のアプリケーションでのみ収集されます。

アップロードとコミット

コード	HTTP	意味と対処
`INVALID_FILE`	400	フォームの `file` フィールドにファイルがありません。
`INVALID_FILENAME`	400	ファイル名にパス区切り文字、`..`、または制御文字が含まれています。
`INVALID_PATH`	400	コミットの `path` にパストラバーサルやシェルの文字が含まれています。
`FILE_TOO_LARGE`	413	zip が 100 MB を超えています。
`UPLOAD_ABORTED`	400	アップロードが終わる前に接続が閉じられました。もう一度アップロードしてください。
`UPLOAD_BUSY`	503	プラットフォームで進行中のアップロードが多すぎます。少し待ってから再試行してください。
`STORAGE_UPLOAD_FAILED`	400	zip を保存できませんでした。後で再試行してください。
`UPLOAD_FAILED`	400	アップロードを処理できませんでした。再試行し、再発する場合は zip を確認してください。
`COMMIT_FAILED`	400	コミットを適用できませんでした。再試行し、再発する場合は zip を確認してください。
`INSUFFICIENT_MEMORY`	400	プランにアプリケーションやデータベースに必要な空きメモリがないか、`MEMORY` が最小値を下回っています。最小値は 256 MB で、`SUBDOMAIN` を持つ Web サイトでは 512 MB です。`MEMORY` を調整するか、何かを削除するか、アップグレードしてください。
`CLUSTER_SELECTION_FAILED`	400	現在、新しいアプリケーションやデータベースを収容できるサーバーがありません。後で再試行してください。
`CLUSTER_MAINTENANCE_TRY_LATER`	503	メンテナンスのため、新しいアプリケーションとデータベースの作成を一時停止しています。後で再試行してください。
`EMPTY_RESPONSE`	400	アップロードを受け取ったサーバーから有効な応答がなかったため、アプリケーションは作成されませんでした。もう一度アップロードしてください。

zip と設定ファイルのチェック

アプリケーションをアップロードすると、それを実行するサーバーが zip とその設定ファイル (squarecloud.app または squarecloud.config) をチェックします。チェックに失敗すると次のいずれかのコードとともに 400 が返され、何もデプロイされません。zip を修正して再度アップロードしてください。コミットは設定ファイルを読み込まないため、この一覧のうち FAILED_EXTRACT または CONTAINER_INSUFFICIENT_DISK_SPACE でしか失敗しません。

コード	HTTP	意味と対処
`FAILED_EXTRACT`	400	zip を展開できませんでした。標準的な zip ツールで作り直し、破損していないことを確認してください。
`DOWNLOAD_FAILED`	400	受信後にサーバーが zip を取得できませんでした。もう一度アップロードしてください。
`MISSING_CONFIG`	400	zip のルートに `squarecloud.app` も `squarecloud.config` もないか、ファイルが空です。
`MISSING_MEMORY`、`MISSING_DISPLAY_NAME`、`MISSING_VERSION`	400	設定ファイルの必須フィールドがないか空です。コードは最初に欠けているフィールドを示します。
`MISSING_MAIN`	400	設定に `MAIN` も `RUNTIME` もありません。どちらかを設定してください。
`INVALID_MAIN`	400	`MAIN` に英字、数字、`_`、`.`、`/`、`-` 以外の文字が含まれているか、32 文字を超えています。`RUNTIME` がない場合は、ファイルが zip にない、空である、プロジェクト外を指している、拡張子がない、または対応言語に一致しない拡張子である場合にも失敗します。
`INVALID_RUNTIME`	400	`RUNTIME` が、設定ファイルのリファレンスに記載された対応値のいずれでもありません。
`INVALID_VERSION`	400	`VERSION` は `recommended` または `latest` である必要があります。正確なバージョン番号は拒否されます。
`INVALID_START`	400	`START` が 256 文字を超えています。
`INVALID_DEPENDENCY`	400	言語の依存関係ファイルがないか空です。JavaScript と TypeScript は `package.json`、Python は `requirements.txt` または `pyproject.toml`、Go は `go.mod` または `go.work`、Rust は `Cargo.toml`、Ruby は `Gemfile`、Elixir は `mix.exs` です。
`INVALID_DISPLAY_NAME`	400	`DISPLAY_NAME` は、英字、数字、スペース、`_`、`-` からなる 1 から 32 文字である必要があります。
`INVALID_DESCRIPTION`	400	`DESCRIPTION` が 280 文字を超えています。
`INVALID_SUBDOMAIN`	400	`SUBDOMAIN` の形式が不正か、予約済みか、すでに使われています。別のものを選んでください。
`CONTAINER_INSUFFICIENT_DISK_SPACE`	400	コミット時に、新しいファイルのためのディスク容量が足りません。不要なファイルを削除して再度コミットしてください。
`ACCESS_FORBIDDEN`	400	このアップロードのためにサーバーがアカウントを読み込めませんでした。再試行し、解決しない場合はサポートに連絡してください。

環境変数

コード	HTTP	意味と対処
`STATIC_APP_ENV_NOT_SUPPORTED`	400	静的サイトは環境変数に対応していません。
`INVALID_ENV_CONTENT`	400	`envs` がないか、形式が誤っています。追加や置き換えにはオブジェクト、削除にはキーの配列を使います。
`TOO_MANY_ENV_VARS`	400	アプリケーションの変数が 256 個を超えてしまいます。
`ENV_NAME_TOO_LONG`	400	キーが 1024 文字を超えているか、文字列ではありません。
`ENV_CONTENT_TOO_LONG`	400	値が 4096 文字を超えています。
`READ_FAILED`	400	アプリケーションから変数を読み取れませんでした。再試行してください。証明書のルートも同じコードを使います。

ファイル

コード	HTTP	意味と対処
`INVALID_PATH`	400	パスにトラバーサルや無効な文字が含まれている、256 文字を超えている、または移動元と移動先が同じです。
`BLOCKED_PATH`	403	パスが保護されたディレクトリ内にあるか、workspace のロールではそのファイルに書き込めません。
`INVALID_ENCODING`	400	`encoding` は `base64` のみ受け付けます。
`INVALID_CONTENT`	400	`content` がない、対応していない形式である、または有効な base64 ではありません。
`FILE_NOT_FOUND`	404	そのパスにファイルもディレクトリもありません。
`FILE_TOO_LARGE`	413	ファイルマネージャーが読み書きできるのは 10 MB までのファイルです。それより大きいファイルにはコミットを使ってください。
`RENAME_FAILED`	400	ファイルを移動または名前変更できませんでした。再試行してください。
`DELETE_FAILED`	400	ファイルを削除できませんでした。再試行してください。
`INVALID_DISPLAY_NAME`、`INVALID_DESCRIPTION`、`INVALID_MEMORY`、`INVALID_AUTORESTART`、`INVALID_SUBDOMAIN`	400	設定ファイルへの書き込みに検証に失敗するフィールド、またはすでに使われている `SUBDOMAIN` が含まれています。そのフィールドを修正してください。
`CANNOT_SET_SUBDOMAIN`	400	Web サイトの設定に `SUBDOMAIN` がありません。Web サイトには常に必要なので、元に戻してください。
`SAVE_FAILED`	500	新しい設定を保存できませんでした。再試行してください。

デプロイと GitHub

コード	HTTP	意味と対処
`INVALID_ACCESS_TOKEN`	400	webhook のトークンが GitHub のトークン (`ghp_...`、`github_pat_...`) でも `@` でもありません。
`MISSING_REQUIRED_FIELDS`	400	`repositoryName` または `repositoryBranch` がありません。
`INVALID_BRANCH_LENGTH`	400	ブランチ名が 256 文字を超えています。
`BRANCH_NOT_FOUND`	400	ブランチがリポジトリに存在しません。
`GIT_ALREADY_CONFIGURED`	400	アプリケーションにはすでに連携済みのリポジトリがあります。先に連携を解除してください。
`GIT_NOT_CONFIGURED`	400	アプリケーションに連携解除するリポジトリがありません。
`GITHUB_NOT_CONNECTED`	403	Square Cloud アカウントに有効な GitHub 接続がありません。ダッシュボードで GitHub を接続または再接続してください。
`REPOSITORY_NOT_AVAILABLE`	403	GitHub アカウントを通じて、Square Cloud GitHub App がリポジトリにインストールされていません。
`REPOSITORY_PERMISSION_REQUIRED`	403	GitHub アカウントにリポジトリへの書き込み権限が必要です。
`REPOSITORY_NOT_FOUND`	404	リポジトリが存在しないか、GitHub アカウントから見えません。
`REPOSITORY_BRANCH_ALREADY_CONFIGURED`	409	いずれかのアカウントの別のアプリケーションが、すでにこのリポジトリとブランチを使っています。
`FAILED_TO_FETCH`	502	GitHub がブランチを確認できませんでした。再試行してください。
`VALIDATION_FAILED`	500 / 502	リポジトリを検証できませんでした。再試行してください。
`VALIDATION_TIMEOUT`	504	リポジトリの検証に時間がかかりすぎました。再試行してください。

Git デプロイの失敗は HTTP エラーではありません。デプロイ履歴に、state: "error" と DEPLOY_FAILED などの code を持つイベントとして表示されます。

ネットワークとドメイン

コード	HTTP	意味と対処
`INVALID_TIME_RANGE`	400	`start` または `end` がないか形式が不正、あるいは `start` が `end` より後です。
`INVALID_FILTER`	400	アナリティクスエンドポイントのフィルターの形式が誤っています。
`UNABLE_TO_FETCH_ANALYTICS`、`UNABLE_TO_FETCH_ERRORS`、`UNABLE_TO_FETCH_PERFORMANCE`	500	エッジプロバイダーがデータを返しませんでした。後で再試行してください。
`ANALYTICS_BUSY`	503	プラットフォーム全体でネットワークアナリティクスが混み合っています。少し待ってから再試行してください。
`NO_CUSTOM_DOMAIN`	400	アプリケーションにカスタムドメインがないため、表示する DNS レコードがありません。
`INVALID_DOMAIN`	400	値が有効なドメイン名ではありません。
`RESERVED_DOMAIN`	400	Square Cloud 自身のドメインとそのサブドメインはカスタムドメインとして使えません。
`DOMAIN_ALREADY_EXISTS`	409	別のアカウントがすでにこのドメインを使っています。先にそちらから削除してください。
`LOAD_BALANCER_LIMIT_REACHED`	403	プランでは、このドメインをこれ以上のアプリケーションに設定できません。上限は `message` に示されます。
`DNS_FAILED`	502	エッジプロバイダーがドメインを割り当てられませんでした。以前のドメインはそのまま残ります。再試行してください。
`PURGE_CACHE_FAILED`	500	キャッシュのパージが完了しませんでした。少し待って再試行してください。

スナップショット

コード	HTTP	意味と対処
`SNAPSHOT_PROCESSING`	202	エラーではありません。スナップショットはまだ生成中です。数分後に一覧を確認してください。
`SNAPSHOT_FAILED`	404	スナップショットを作成できませんでした。後で再試行してください。
`MISSING_PARAMETERS`	400	`snapshotId` または `versionId` がありません。
`INVALID_SNAPSHOT_ID`	400	`snapshotId` がスナップショット一覧の `name` ではありません。
`INVALID_VERSION_ID`	400	`versionId` がスナップショット一覧の `version_id` ではありません。
`SNAPSHOT_NOT_FOUND`	404	その id とバージョンに一致するスナップショットがありません。
`SNAPSHOT_RESTORE_FAILED`	404	復元に失敗しました。再試行するか、別のスナップショットを復元してください。
`SNAPSHOT_DATABASE_MISMATCH`	400	スナップショットのデータベースエンジンが、復元先のデータベースと異なります。
`INVALID_SCOPE`	400	アカウントのスナップショット一覧の `scope` は `applications` または `databases` である必要があります。

データベース

コード	HTTP	意味と対処
`DATABASE_NOT_FOUND`	404	データベースが存在しないか、自分のものではありません。
`INVALID_NAME`	400	名前は 1 から 32 文字である必要があります。workspace も同じルールです。
`INVALID_DATABASE_TYPE`	400	`type` は `mongo`、`mysql`、`postgres`、`redis` のいずれかである必要があります。
`INVALID_DATABASE_VERSION`	400	そのエンジンでは、このバージョンを利用できません。
`INVALID_MEMORY`	400	このエンジンまたはプランでは、そのメモリは無効です。
`DATABASE_CREATION_FAILED`	400 / 500	データベースを作成できませんでした。何も残っていないため、再試行できます。
`DATABASE_NOT_RUNNING`	400	証明書の取得や認証情報のリセットの前に、データベースを起動してください。
`INVALID_RESET_TYPE`	400	`reset` は `password` または `certificate` である必要があります。
`RESET_FAILED`	500	認証情報をリセットできませんでした。再試行してください。
`NO_UPDATE_DATA`	400	データベースを更新するには、`name`、`ram`、またはその両方を送信してください。

workspace

コード	HTTP	意味と対処
`WORKSPACE_NOT_FOUND`	404	workspace が存在しないか、オーナーでもメンバーでもありません。
`WORKSPACE_LIMIT_REACHED`	400	アカウントはすでにプランで許可される上限数の workspace を持っています。
`WORKSPACE_CREATION_FAILED`	400	workspace を作成できませんでした。再試行してください。
`INVALID_CODE`	400	招待コードがない、形式が不正、または期限切れです。相手に新しいコードを依頼してください。
`INVALID_GROUP`	400	`group` は `view`、`manager`、`maintain`、`admin` のいずれかである必要があります。
`CANNOT_INVITE_OWNER`	400	招待コードは自分のもので、すでにその workspace のオーナーです。
`CANNOT_EDIT_OWNER`	400	オーナーのロールは変更できません。
`CANNOT_LEAVE_OWNER`	400	オーナーは workspace から退出できません。代わりに削除してください。
`MEMBERS_LIMIT_REACHED`	400	workspace はすでにオーナーのプランで許可される上限数のメンバーを持っています。
`MEMBER_ALREADY_ADDED`	400	その人はすでにメンバーです。
`MEMBER_NOT_FOUND`	400 / 404	`memberId` がない (`400`) か、その人はもうメンバーではありません (`404`)。
`APPLICATIONS_LIMIT_REACHED`	400	workspace はすでに 100 個のアプリケーションを共有しています。
`APP_ALREADY_IN_WORKSPACE`	400	アプリケーションはすでにこの workspace で共有されています。

プラットフォーム

コード	HTTP	意味と対処
`INTERNAL_SERVER_ERROR`	500	予期しないエラーです。一度再試行し、解決しない場合はサポートに連絡してください。
`DATABASE_UNAVAILABLE`	503	プラットフォームのデータベースが一時的に利用できません。数秒後に再試行してください。この状態で、既存のリソースが「見つからない」と報告されることはありません。
`CLUSTER_TIMEOUT`	400	リソースをホストするサーバーが時間内に応答しませんでした。再試行してください。
`CLUSTER_UNAVAILABLE`	400	リソースをホストするサーバーに現在接続できません。少し待って再試行してください。
`REQUEST_ABORTED`	400	リソースをホストするサーバーが応答する前にリクエストがキャンセルされました。再試行してください。
`INVALID_PARAMETERS`	400	内部リクエストの形式が不正でした。再試行し、解決しない場合はサポートに連絡してください。

AI_* のコード (AI_DAILY_LIMIT_REACHED、AI_NO_PLAN_LIMIT_REACHED、AI_MAX_CONCURRENT_STREAMS、AI_UNAVAILABLE) は、ダッシュボードのセッションが必要なダッシュボードの AI アシスタントのものです。API キーでこれらを受け取ることはありません。

はじめに

アカウント

アプリケーション

データベース

ワークスペース

AI

API のエラーコードと対処方法

エラーの形式

再試行

レート制限

認証と権限

リクエストの検証

クォータと接続数の制限

アプリケーション

アップロードとコミット

zip と設定ファイルのチェック

環境変数

ファイル

デプロイと GitHub

ネットワークとドメイン

スナップショット

データベース

workspace

プラットフォーム

関連項目

​エラーの形式

​再試行

​レート制限

​認証と権限

​リクエストの検証

​クォータと接続数の制限

​アプリケーション

​アップロードとコミット

​zip と設定ファイルのチェック

​環境変数

​ファイル

​デプロイと GitHub

​ネットワークとドメイン

​スナップショット

​データベース

​workspace

​プラットフォーム

​関連項目

エラーの形式

再試行

レート制限

認証と権限

リクエストの検証

クォータと接続数の制限

アプリケーション

アップロードとコミット

zip と設定ファイルのチェック

環境変数

ファイル

デプロイと GitHub

ネットワークとドメイン

スナップショット

データベース

workspace

プラットフォーム

関連項目