Skip to main content
API とネットワークのあらゆる失敗は、1 つの例外 SquareCloudAPIError として送出されます。

SquareCloudAPIError

SquareCloudAPIError は Exception のサブクラスです。 str(error) は <METHOD> <path>: HTTP <status> <CODE>: <message> です。ステータスが 0 の場合は HTTP <status> が、メッセージが空の場合は : <message> が省かれます。 次の 2 つの失敗はラップされません:
  • 空のキーや空白だけの API キーは、クライアントのコンストラクタで ValueError を送出します。
  • ローカルファイルの問題は OSError を送出します: 開けないアップロードパス、アップロード中に読み取れなくなったファイル、書き込めない download_snapshot の保存先。

SDK のコード

コードは文字列

code はプレーンな str で、SDK にはコードの列挙型はありません。SquareCloudAPIError の docstring に既知の API コードがすべて列挙されており、以下のグループにも掲載しています。 API コードの一覧は増えていきます。不明なコードは HTTP ステータスで処理してください:

すべての呼び出しで発生しうるエラー

グループ別の API コード

APP_NOT_FOUND, DATABASE_NOT_FOUND, WORKSPACE_NOT_FOUND, MEMBER_NOT_FOUND, FILE_NOT_FOUND, SNAPSHOT_NOT_FOUND, REPOSITORY_NOT_FOUND, BRANCH_NOT_FOUND, ROUTE_NOT_FOUND
INVALID_ACCESS_TOKEN, INVALID_AUTORESTART, INVALID_BRANCH_LENGTH, INVALID_CODE, INVALID_CONTENT, INVALID_CONTENT_TYPE, INVALID_DATABASE_TYPE, INVALID_DATABASE_VERSION, INVALID_DESCRIPTION, INVALID_DISPLAY_NAME, INVALID_DOMAIN, INVALID_ENCODING, INVALID_ENV_CONTENT, INVALID_FILE, INVALID_FILENAME, INVALID_FILTER, INVALID_GROUP, INVALID_ID, INVALID_INPUT, INVALID_JSON_BODY, INVALID_MEMORY, INVALID_NAME, INVALID_PARAMETERS, INVALID_PATH, INVALID_RESET_TYPE, INVALID_SCOPE, INVALID_SNAPSHOT_ID, INVALID_SUBDOMAIN, INVALID_TIME_RANGE, INVALID_VERSION_ID, MISSING_PARAMETERS, MISSING_REQUIRED_FIELDS, NO_UPDATE_DATA, VALIDATION_FAILED, VALIDATION_TIMEOUT, ENV_NAME_TOO_LONG, ENV_CONTENT_TOO_LONG, TOO_MANY_ENV_VARS, RESERVED_DOMAIN, CANNOT_SET_SUBDOMAIN, STATIC_APP_ENV_NOT_SUPPORTED
ACCESS_DENIED, MISSING_SCOPE, RESOURCE_NOT_ALLOWED, PERMISSION_DENIED, SCOPE_NOT_GRANTABLE, BLOCKED_PATH, UPGRADE_REQUIRED
RATE_LIMITED, KEEP_CALM, APPLICATIONS_LIMIT_REACHED, WORKSPACE_LIMIT_REACHED, MEMBERS_LIMIT_REACHED, LOAD_BALANCER_LIMIT_REACHED, DAILY_SNAPSHOTS_LIMIT_REACHED, INSUFFICIENT_MEMORY, FILE_TOO_LARGE, PAYLOAD_TOO_LARGE, REALTIME_MAX_CONNECTIONS, REALTIME_MAX_CONNECTIONS_APP, AI_DAILY_LIMIT_REACHED, AI_MAX_CONCURRENT_STREAMS, AI_NO_PLAN_LIMIT_REACHED
CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_TEMPORARILY_SUSPENDED, CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT, ACTION_FAILED, DATABASE_NOT_RUNNING
UPLOAD_BUSY, UPLOAD_FAILED, UPLOAD_ABORTED, STORAGE_UPLOAD_FAILED, COMMIT_FAILED, READ_FAILED, SAVE_FAILED, RENAME_FAILED, DELETE_FAILED, REQUEST_ABORTED, EMPTY_RESPONSE
SNAPSHOT_FAILED, SNAPSHOT_PROCESSING, SNAPSHOT_RESTORE_FAILED, SNAPSHOT_DATABASE_MISMATCH, RESTORE_IN_PROGRESS
GIT_ALREADY_CONFIGURED, GIT_NOT_CONFIGURED, GITHUB_NOT_CONNECTED, REPOSITORY_BRANCH_ALREADY_CONFIGURED, REPOSITORY_NOT_AVAILABLE, REPOSITORY_PERMISSION_REQUIRED, FAILED_TO_FETCH
ANALYTICS_BUSY, UNABLE_TO_FETCH_ANALYTICS, UNABLE_TO_FETCH_ERRORS, UNABLE_TO_FETCH_PERFORMANCE, DNS_FAILED, DOMAIN_ALREADY_EXISTS, NO_CUSTOM_DOMAIN, PURGE_CACHE_FAILED, LOGS_UNAVAILABLE, METRICS_NOT_SUPPORTED
DATABASE_CREATION_FAILED, DATABASE_UNAVAILABLE, RESET_FAILED, WORKSPACE_CREATION_FAILED, APP_ALREADY_IN_WORKSPACE, MEMBER_ALREADY_ADDED, CANNOT_EDIT_OWNER, CANNOT_INVITE_OWNER, CANNOT_LEAVE_OWNER, CONFLICTING_RESOURCES
INTERNAL_SERVER_ERROR, CLUSTER_MAINTENANCE_TRY_LATER, CLUSTER_SELECTION_FAILED, CLUSTER_TIMEOUT, CLUSTER_UNAVAILABLE, AI_UNAVAILABLE
RATE_LIMIT と RATE_LIMIT_EXCEEDED は非推奨としてマークされたうえで一覧に残っています。現在 API はどちらの場合も RATE_LIMITED を返します。
ai.chat() のエラーは、代わりに小文字の OpenAI コード (access_denied、rate_limit_exceeded、server_overloaded など) を使います。AI を参照してください。

リトライ

SDK は安全に繰り返せるものだけを、最大 max_retries 回 (デフォルトは 2 なので、最大 3 回の試行) リトライします: 次のものは決してリトライしません:
  • TIMEOUT
  • すべての 429: RATE_LIMITED は約 30 分のブロックである可能性があり、KEEP_CALM もリトライされません
  • その他の 5xx
  • AI のエラー
503 DATABASE_UNAVAILABLE は変更がすでに適用された後に返されることがあるため、SDK は GET 以外ではリトライしません。必要であれば、冪等な変更は自分でリトライしてください。 リトライ n 回目 (0 から開始) の前の待機時間は min(8 s, 500 ms · 2^n) · U(0.5, 1) です。50%〜100% のジッターを伴う指数バックオフです。リトライを無効にするには max_retries=0 を設定します。

タイムアウト

timeout (30 秒) はリクエスト全体ではなく、ソケット操作ごと (接続と、各読み取り・書き込み) に適用されます。120 秒の下限がある呼び出しとタイムアウトのない呼び出しについては、タイムアウトを参照してください。タイムアウトはステータス 0 の TIMEOUT を送出し、リトライされることはありません。

レート制限

すべてのアカウントには、プランによって決まる 60 秒あたりのリクエスト数の制限があり (値)、一部のルートには独自の制限があります:
  • 429 RATE_LIMITED: アカウント、API キー、または IP のブロックで、約 30 分続くことがあります。ネットワーク系 endpoint と account.snapshots の制限でもあります。
  • 429 KEEP_CALM: 短時間に 1 つのルートへの呼び出しが多すぎる。
SDK は 429 を決してリトライしません。ペースを落とし、しばらく待ってから再試行してください。