Restore now tells you whether the restore is still running, and Metrics takes a range. Everything else is added on top: two new operations, for 69 in all, new fields and new error codes.
At a glance
Import path
Only the import path changes.New and every Option keep their signatures and defaults, and the default User-Agent becomes squarecloud-sdk-go/4.0.0.
Breaking changes
The samples below run inside a function that returns anerror.
Snapshot restore
Apps.Snapshots.Restore and Databases.Snapshots.Restore return (SnapshotRestored, error) instead of error. A restore that takes longer than about 90 seconds keeps running after the call returns. v3 returned nil for it, so callers reported “restored” while it was still running. v4 returns Pending: true for it, and Pending: false for a finished restore.
RestoreState reports queued or running while the restore runs, with the current Step, then success or error, with a Code, for 1 hour after it ends. It reports none after that hour or when there was no recent restore. It allows 30 calls a minute. See Snapshots.
Metrics
Apps.Metrics and Databases.Metrics take a range as their last argument. Pass "" to keep the v3 behavior, which covers the last 24 hours.
"7d" returns hourly points with the hour’s average and its CPUMax and RAMMax peaks, on the Pro and Enterprise plans for apps of 512 MB or more. Other plans and smaller apps get the 24-hour answer without an error, so check the points instead of assuming 7 days. Any other range returns 400 INVALID_PARAMETERS. For databases, "7d" needs a Pro or Enterprise plan. See Metrics.
RESTORE_IN_PROGRESS is 409
RESTORE_IN_PROGRESS moved from 403 to 409 on app and database delete and on database start and stop. It is also new, as 409, on app start, stop and restart and on snapshot Create and Restore. Match the code alone:
New types and fields
The new fields break only struct literals of these types that leave out the field names. Use field names.
Errors
- New constants:
CodeAIWeeklyLimitReached,CodeEnvBusy(409),CodeGitBranchDeletedandCodeGitRefNotSupported(sent only to GitHub push webhooks),CodeRestoreInterrupted,CodeSnapshotsUnavailable(503),CodeSnapshotCorrupt,CodeSnapshotInProgress(409),CodeSnapshotRestoreProcessing(reported asSnapshotRestored.Pending, never as an error),CodeWriteFailed, andCodeWrongHost(421, never returned to the calls of this SDK). CodeMetricsNotSupportedis deprecated but kept.- A restore can fail with more codes than
SNAPSHOT_RESTORE_FAILED. See Snapshots for the full list. - The SDK retries none of the new codes.
SNAPSHOTS_UNAVAILABLEasks you to wait about 30 seconds andCLUSTER_MAINTENANCE_TRY_LATERlasts minutes, both longer than the retry waits. A 409 from a busy resource is yours to decide. - The SDK’s own errors,
INVALID_API_KEY,INVALID_IDandFILE_TOO_LARGE, have new messages that say what went wrong and how to fix it. CompareCode, notMessage.
Behavior changes
- Snapshot links expire after 1 hour. They used to last 30 days, so download right after listing or creating a snapshot. Only
Createcan return an emptyURLandKey, withPending: false, when the API key lackssnapshots:read. - Snapshot listings (
Account.Snapshots,Apps.Snapshots.ListandDatabases.Snapshots.List) return 503SNAPSHOTS_UNAVAILABLEinstead of an empty list when snapshot storage cannot answer. - Metrics. Apps below 512 MB now have metrics, with one point every 10 minutes, where they used to get 400
METRICS_NOT_SUPPORTED. - Environment variables.
Envs.Set,Envs.ReplaceandEnvs.Deletereturn 409ENV_BUSYwhen another write is in progress. With an API key that lacksenvs:read,Envs.Setreturns only the variables you sent, not the full set, andEnvs.Deletereturns an empty set. - Files.
Files.ReadandFiles.Writecan return 400READ_FAILEDandWRITE_FAILED, andCommitcan return 403BLOCKED_PATH. - Parallel uploads. The API limits how many large uploads an account can send at the same time. Going over the limit returns 429
RATE_LIMITED, which the SDK never retries. - AI. A 429 from
AI.Chatcan beweekly_limit_reached. - User-Agent is
squarecloud-sdk-go/4.0.0.
Checklist
1
Change the import path
Import
github.com/squarecloudofc/sdk-api-go/v4 everywhere and run go get github.com/squarecloudofc/sdk-api-go/v4@v4.0.0.2
Follow pending restores
Replace
err := c.Apps.Snapshots.Restore(...) with res, err := .... When res.Pending is true, poll RestoreState, for example every 10 seconds, until State is success or error. Never send the restore again.3
Pass a range to Metrics
Add
"", "24h" or "7d" as the last argument of Apps.Metrics and Databases.Metrics.4
Match 409 RESTORE_IN_PROGRESS
Match
409 where you matched 403, or match the code alone.5
Handle 503 SNAPSHOTS_UNAVAILABLE
Handle it on snapshot listings, instead of reading an empty list as “no snapshots”.
6
Compare codes, not messages
Check
Code wherever you compared the Message of INVALID_API_KEY, INVALID_ID or FILE_TOO_LARGE.Next steps
Client
Install the SDK and create a client.
Snapshots
Create, restore and follow snapshots.
Errors
Error class, retries and rate limits.

