Skip to main content
Jeder API-, Netzwerk- und lokale Fehler hat einen einzigen Typ: *squarecloud.APIError. Untersuche ihn mit errors.As. Die kürzeren Snippets unten laufen in dem Programm aus Beispiele ausführen: Füge jeweils eines in main ein und führe goimports aus.

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. 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). Die Liste der API-Codes wächst. Behandle einen unbekannten Code anhand seines HTTP-Status:

API-Fehlercodes

Alle anderen Codes kommen von der API. Die Referenz der API-Fehler listet jeden mit seinem HTTP-Status, seiner Bedeutung und der Lösung auf, und jede SDK-Seite nennt die Codes, die ihre Methoden am häufigsten zurückgeben. Jeder Aufruf kann außerdem 401 ACCESS_DENIED (ein falscher Schlüssel), 403 MISSING_SCOPE oder RESOURCE_NOT_ALLOWED (die Grenzen des Schlüssels), 429 (siehe Rate Limits) oder 503 DATABASE_UNAVAILABLE zurückgeben. 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: Das Konto oder der API-Schlüssel hat sein Anfragekontingent überschritten und ist für etwa 30 Minuten gesperrt, oder eine IP, die wiederholt ungültige Schlüssel sendet, wird für kurze Zeit gesperrt. 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.

Nächste Schritte

Referenz der API-Fehler

Jeder Fehlercode mit Bedeutung und Lösung.

Limits und Beschränkungen

Die Anfragelimits jedes Plans.