Skip to main content
Jeder API-, Netzwerk- und lokale Fehler hat einen einzigen Typ: *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, dessen ctx 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:
Einige Fehler sind kein *APIError:
  • Realtime.Next gibt das reine ctx.Err() zurück, wenn sein ctx endet, und io.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, die encoding/json nicht kodieren kann, und ein Fehler des an DownloadSnapshot übergebenen io.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

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
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).
Fehler von 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 zu WithMaxRetries Mal (Standard 2, also bis zu 3 Versuche): Nie wiederholt werden:
  • TIMEOUT;
  • jedes 429: RATE_LIMITED kann eine Sperre von etwa 30 Minuten sein, und auch KEEP_CALM wird nicht wiederholt;
  • andere 5xx;
  • KI-Fehler.
503 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 von Account.Snapshots.
  • 429 KEEP_CALM: zu viele Aufrufe an eine Route in kurzer Zeit.
Das SDK wiederholt ein 429 nie. Werde langsamer und warte, bevor du es erneut versuchst.