Skip to main content
Jeder API-, Netzwerk- und lokale Fehler wirft eine einzige Klasse: SquareCloudAPIError. Die Beispiele verwenden den Client api aus Client erstellen. appId ist die ID einer deiner Apps: api.account.me() listet sie auf.

SquareCloudAPIError

SquareCloudAPIError erweitert Error (es ist kein TypeError). Zwei Fehler werden nicht verpackt:
  • Ein abgebrochener Aufruf wird mit dem reason des Signals abgelehnt. Eine abgebrochene realtime()-Schleife endet einfach.
  • Ein Upload-Pfad, der sich nicht öffnen lässt, wirft den Dateisystemfehler.

Codes des SDK

Der Typ ErrorCode

ErrorCode ist nur ein Typ (kein Laufzeitobjekt). Er listet jeden öffentlichen API-Code, die veralteten und die des SDK, plus string & {}, sodass dein Editor bekannte Codes vervollständigt und neue Codes trotzdem die Typprüfung bestehen. RATE_LIMIT und RATE_LIMIT_EXCEEDED sind weiterhin im Typ enthalten und als veraltet markiert: Die API antwortet jetzt in beiden Fällen mit RATE_LIMITED. 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, …). Siehe KI.

Wiederholungen

Das SDK wiederholt nur, was sich gefahrlos wiederholen lässt, bis zu maxRetries 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. 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 maxRetries: 0, um Wiederholungen abzuschalten.

Timeouts

timeoutMs (30 s) gilt pro Versuch und deckt die gesamte Antwort ab. Unter Timeouts findest du die Aufrufe mit einem Mindestwert von 120 s und die Aufrufe ohne Timeout. Ein Timeout wirft TIMEOUT mit Status 0 und wird nie wiederholt.

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.