> ## Documentation Index > Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt > Use this file to discover all available pages before exploring further. # JavaScript-SDK: Fehler und Wiederholungen > Behandle SquareCloudAPIError in @squarecloud/api: Status, Code und Nachricht, die eigenen Fehlercodes des SDK, Wiederholungen, Timeouts und Rate Limits. Jeder API-, Netzwerk- und lokale Fehler wirft eine einzige Klasse: `SquareCloudAPIError`. Die Beispiele verwenden den Client `api` aus [Client erstellen](/de/sdks/js/client#client-erstellen). `appId` ist die ID einer deiner Apps: [`api.account.me()`](/de/sdks/js/client#konto) listet sie auf. ```typescript theme={"system"} import { SquareCloudAPI, SquareCloudAPIError } from "@squarecloud/api"; try { await api.apps.start(appId); } catch (error) { if (error instanceof SquareCloudAPIError) { console.error(error.status, error.code, error.message); console.error(error.method, error.path); // "POST" "/v2/apps//start" } } ``` ## `SquareCloudAPIError` `SquareCloudAPIError` erweitert `Error` (es ist **kein** `TypeError`). | Eigenschaft | Typ | Beschreibung | | - | - | - | | `status` | `number` | HTTP-Status. `0`, wenn keine Antwort eingetroffen ist (Netzwerkfehler, Timeout, lokale Prüfung) | | `code` | `ErrorCode` | Der Fehlercode der API, z. B. `APP_NOT_FOUND`, oder einer der Codes des SDK | | `message` | `string` | Die Erklärung des Servers. Hat der Server nur einen Code gesendet, der Code selbst | | `method` | `string` | HTTP-Methode des fehlgeschlagenen Aufrufs | | `path` | `string` | URL-Pfad des fehlgeschlagenen Aufrufs, ohne den Query-String | | `cause` | `unknown` | Der ursprüngliche Fehler, bei `NETWORK_ERROR` und ungültigem JSON | 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 | Status | Code | Wann | | - | - | - | | 0 | `NETWORK_ERROR` | Keine Antwort (DNS, Verbindung zurückgesetzt, Body abgeschnitten). Der ursprüngliche Fehler steht in `cause` | | 0 | `TIMEOUT` | Keine Antwort innerhalb des [Timeouts](/de/sdks/js/client#timeouts) | | 0 | `FILE_TOO_LARGE` | Lokale Prüfung: ein Upload über 100 MB oder ein `files.write` über 10 MB. Es wurde nichts gesendet | | 0 | `INVALID_ID` | Lokale Prüfung: eine ID, die leer, `.` oder `..` ist. Es wurde nichts gesendet | | beliebig | `UNKNOWN_ERROR` | Eine Antwort ohne Code (etwa die Fehlerseite eines Proxys), mit dem echten `status` und der Nachricht `HTTP `. Ein 2xx-Body, der kein JSON ist, hat die Nachricht `Invalid JSON in HTTP response` | ## 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**: ```typescript theme={"system"} async function start(appId: string) { try { await api.apps.start(appId); } catch (error) { if (!(error instanceof SquareCloudAPIError)) throw error; switch (error.code) { case "APP_NOT_FOUND": return null; case "CONTAINER_ALREADY_STARTED": return; // fine default: if (error.status === 429) return retryLater(); if (error.status >= 500) return reportOutage(error); throw error; } } } ``` ## API-Fehlercodes Alle anderen Codes kommen von der API. Die [Referenz der API-Fehler](/de/api-reference/errors) 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](/de/sdks/js/client#api-schlüssel-und-scopes)), 429 (siehe [Rate Limits](#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](/de/sdks/js/ai#fehler). ## Wiederholungen Das SDK wiederholt nur, was sich gefahrlos wiederholen lässt, bis zu `maxRetries` Mal (Standard `2`, also bis zu 3 Versuche): | Wiederholt | Methoden | | - | - | | `NETWORK_ERROR` | Nur `GET` | | 503 `UPLOAD_BUSY` | Jede Methode | | 503 `ANALYTICS_BUSY` | Jede Methode | | 503 `DATABASE_UNAVAILABLE` | Nur `GET` | **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](/de/sdks/js/client#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](/de/api-reference/limitations-and-restrictions)), 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 Jeder Fehlercode mit Bedeutung und Lösung. Die Anfragelimits jedes Plans. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.