*squarecloud.APIError. Untersuche ihn mit errors.As.
APIError
Unwrap() gibt die Ursache zurück (den Transport-, Dekodier- oder Kontextfehler) bei NETWORK_ERROR, TIMEOUT und ungültigem JSON, sonst nil. Error() erzeugt squarecloud: <METHOD> <path>: HTTP <status> <CODE>: <message>, ohne HTTP <status>, wenn der Status 0 ist, und ohne : <message>, wenn die Nachricht leer ist. Prüfe die Felder, nicht diesen Text.
Abgebrochene und abgelaufene Kontexte
Ein Aufruf, dessenctx abgebrochen wird, gibt einen *APIError mit NETWORK_ERROR zurück, und einer, dessen Deadline abläuft, gibt TIMEOUT zurück, beide mit Status 0. Sie lassen sich zum Fehler des Kontexts entpacken:
*APIError:
Realtime.Nextgibt das reinectx.Err()zurück, wenn seinctxendet, undio.EOF, wenn der Stream normal endet.- Probleme auf Seite des Aufrufers sind einfache Fehler: ein
nil-Upload-Reader, eine Snapshot-URL oder Basis-URL, die sich nicht parsen lässt, eine Eingabe, dieencoding/jsonnicht kodieren kann, und ein Fehler des anDownloadSnapshotübergebenenio.Writer.
Codes des SDK
Code*-Konstanten
Code ist ein einfacher string. Das Paket hat eine Konstante pro öffentlichem API-Code, benannt nach ihm im Go-Stil (CodeAppNotFound für APP_NOT_FOUND, CodeInvalidID, CodeDNSFailed, …), dazu die oben genannten eigenen Codes des SDK.
Die Liste der API-Codes wächst. Behandle einen unbekannten Code anhand seines HTTP-Status:
Fehler bei jedem Aufruf
API-Codes nach Gruppen
Nicht gefunden
Nicht gefunden
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_FOUNDValidierung
Validierung
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_SUPPORTEDAuthentifizierung und Berechtigungen
Authentifizierung und Berechtigungen
ACCESS_DENIED, MISSING_SCOPE, RESOURCE_NOT_ALLOWED, PERMISSION_DENIED, SCOPE_NOT_GRANTABLE, BLOCKED_PATH, UPGRADE_REQUIREDLimits und Rate Limits
Limits und Rate Limits
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_REACHEDContainer (Starten, Stoppen, Neustarten)
Container (Starten, Stoppen, Neustarten)
CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_TEMPORARILY_SUSPENDED, CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT, ACTION_FAILED, DATABASE_NOT_RUNNINGUploads, Dateien und Commits
Uploads, Dateien und Commits
UPLOAD_BUSY, UPLOAD_FAILED, UPLOAD_ABORTED, STORAGE_UPLOAD_FAILED, COMMIT_FAILED, READ_FAILED, SAVE_FAILED, RENAME_FAILED, DELETE_FAILED, REQUEST_ABORTED, EMPTY_RESPONSESnapshots
Snapshots
SNAPSHOT_FAILED, SNAPSHOT_PROCESSING, SNAPSHOT_RESTORE_FAILED, SNAPSHOT_DATABASE_MISMATCH, RESTORE_IN_PROGRESSDeploys und GitHub
Deploys und GitHub
GIT_ALREADY_CONFIGURED, GIT_NOT_CONFIGURED, GITHUB_NOT_CONNECTED, REPOSITORY_BRANCH_ALREADY_CONFIGURED, REPOSITORY_NOT_AVAILABLE, REPOSITORY_PERMISSION_REQUIRED, FAILED_TO_FETCHNetzwerk und Domains
Netzwerk und Domains
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_SUPPORTEDDatenbanken und Workspaces
Datenbanken und Workspaces
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_RESOURCESPlattform
Plattform
INTERNAL_SERVER_ERROR, CLUSTER_MAINTENANCE_TRY_LATER, CLUSTER_SELECTION_FAILED, CLUSTER_TIMEOUT, CLUSTER_UNAVAILABLE, AI_UNAVAILABLEVeraltet
Veraltet
CodeRateLimit (RATE_LIMIT) und CodeRateLimitExceeded (RATE_LIMIT_EXCEEDED) werden weiterhin exportiert und sind als veraltet markiert: Die API antwortet jetzt in beiden Fällen mit RATE_LIMITED (CodeRateLimited).AI.Chat verwenden stattdessen kleingeschriebene OpenAI-Codes (access_denied, rate_limit_exceeded, server_overloaded, …), die Code unverändert enthält. Siehe KI.
Wiederholungen
Das SDK wiederholt nur, was sich gefahrlos wiederholen lässt, bis zuWithMaxRetries Mal (Standard 2, also bis zu 3 Versuche):
Nie wiederholt werden:
TIMEOUT;- jedes 429:
RATE_LIMITEDkann eine Sperre von etwa 30 Minuten sein, und auchKEEP_CALMwird nicht wiederholt; - andere 5xx;
- KI-Fehler.
DATABASE_UNAVAILABLE kann eintreffen, nachdem eine Mutation bereits angewendet wurde, daher wiederholt das SDK ihn außerhalb von GET nicht. Wiederhole deine eigenen idempotenten Mutationen, wenn nötig. Ein Upload wird nur wiederholt, wenn sein Body erneut abgespielt werden kann: ein io.ReaderAt mit bekannter Größe, etwa eine *os.File (siehe Commit und Upload).
Die Wartezeit vor Wiederholung n (ab 0) beträgt min(8 s, 500 ms · 2^n) · U(0.5, 1): exponentielles Backoff mit 50 % bis 100 % Jitter. Setze WithMaxRetries(0), um Wiederholungen abzuschalten.
Timeouts
WithTimeout (30 s) gilt nur, wenn ctx keine Deadline hat, und eine Deadline deckt den gesamten Aufruf ab, einschließlich Wiederholungen und Backoff-Wartezeiten. Unter Timeouts findest du die Aufrufe mit einem Mindestwert von 2 Minuten und die Aufrufe ohne Standard-Deadline. Eine abgelaufene Deadline gibt TIMEOUT mit Status 0 zurück, wird nie wiederholt und lässt sich zu context.DeadlineExceeded entpacken.
Rate Limits
Jedes Konto hat ein Limit an Anfragen pro 60 Sekunden, das sein Plan festlegt (Werte), und manche Routen haben ein eigenes:- 429
RATE_LIMITED: eine Sperre des Kontos, API-Schlüssels oder der IP, die etwa 30 Minuten dauern kann. Auch das Limit der Netzwerk-Endpoints und vonAccount.Snapshots. - 429
KEEP_CALM: zu viele Aufrufe an eine Route in kurzer Zeit.

