*squarecloud.APIError で表されます。errors.As で確認してください。
APIError
Unwrap() は、NETWORK_ERROR、TIMEOUT、無効な JSON の場合はその原因 (トランスポート、デコード、または context のエラー) を返し、それ以外では nil を返します。Error() は squarecloud: <METHOD> <path>: HTTP <status> <CODE>: <message> を出力します。ステータスが 0 の場合は HTTP <status> が、メッセージが空の場合は : <message> が省かれます。このテキストではなく、フィールドで判定してください。
キャンセルされた context と期限切れの context
ctx がキャンセルされた呼び出しは NETWORK_ERROR の *APIError を返し、期限を過ぎた呼び出しは TIMEOUT を返します。どちらもステータスは 0 です。これらは context のエラーにアンラップされます:
*APIError ではありません:
Realtime.Nextは、そのctxが終了すると素のctx.Err()を返し、ストリームが正常に終了するとio.EOFを返します。- 呼び出し側の問題は通常のエラーです:
nilのアップロードリーダー、解析できない snapshot URL またはベース URL、encoding/jsonでエンコードできない入力、そしてDownloadSnapshotに渡したio.Writerのエラー。
SDK のコード
Code* 定数
Code は通常の string です。パッケージには、公開されている API コードごとに、Go のスタイルで名付けられた定数が 1 つずつあり (APP_NOT_FOUND に対する CodeAppNotFound、CodeInvalidID、CodeDNSFailed など)、さらに上記の SDK 独自のコードもあります。
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アップロード、ファイル、commit
アップロード、ファイル、commit
UPLOAD_BUSY, UPLOAD_FAILED, UPLOAD_ABORTED, STORAGE_UPLOAD_FAILED, COMMIT_FAILED, READ_FAILED, SAVE_FAILED, RENAME_FAILED, DELETE_FAILED, REQUEST_ABORTED, EMPTY_RESPONSESnapshot
Snapshot
SNAPSHOT_FAILED, SNAPSHOT_PROCESSING, SNAPSHOT_RESTORE_FAILED, SNAPSHOT_DATABASE_MISMATCH, RESTORE_IN_PROGRESSDeploy と GitHub
Deploy と GitHub
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データベースと workspace
データベースと workspace
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非推奨
非推奨
CodeRateLimit (RATE_LIMIT) と CodeRateLimitExceeded (RATE_LIMIT_EXCEEDED) は非推奨としてマークされたうえで、引き続きエクスポートされています。現在の API はどちらの場合も RATE_LIMITED (CodeRateLimited) を返します。AI.Chat のエラーは、代わりに OpenAI の小文字のコード (access_denied、rate_limit_exceeded、server_overloaded など) を使い、Code にはそれがそのまま入ります。AI を参照してください。
リトライ
SDK は安全に繰り返せるものだけを、最大WithMaxRetries 回 (デフォルトは 2 なので、最大 3 回の試行) リトライします:
次のものは決してリトライしません:
TIMEOUT;- すべての 429:
RATE_LIMITEDは約 30 分のブロックである可能性があり、KEEP_CALMもリトライされません; - その他の 5xx;
- AI のエラー。
DATABASE_UNAVAILABLE は変更がすでに適用された後に返されることがあるため、SDK は GET 以外ではリトライしません。必要であれば、冪等な変更は自分でリトライしてください。アップロードがリトライされるのは、ボディを再送できる場合だけです。つまり、*os.File のようにサイズがわかっている io.ReaderAt です (Commit とアップロードを参照)。
リトライ n 回目 (0 から開始) の前の待機時間は min(8 s, 500 ms · 2^n) · U(0.5, 1) です。50%〜100% のジッターを伴う指数バックオフです。リトライを無効にするには WithMaxRetries(0) を設定します。
タイムアウト
WithTimeout (30 秒) は ctx に期限がない場合にのみ適用され、1 つの期限がリトライとバックオフの待機時間を含む呼び出し全体を対象とします。2 分の下限がある呼び出しと、デフォルトの期限がない呼び出しについては、タイムアウトを参照してください。期限を過ぎるとステータス 0 の TIMEOUT が返され、リトライされることはなく、context.DeadlineExceeded にアンラップされます。
レート制限
すべてのアカウントには、プランによって決まる 60 秒あたりのリクエスト数の制限があり (値)、一部のルートには独自の制限があります:- 429
RATE_LIMITED: アカウント、API キー、または IP のブロックで、約 30 分続くことがあります。ネットワーク系 endpoint とAccount.Snapshotsの制限でもあります。 - 429
KEEP_CALM: 短時間に 1 つのルートへの呼び出しが多すぎる。

