Python-SDK: Fehler und Wiederholungen

Jeder API- und Netzwerkfehler wirft eine einzige Exception: SquareCloudAPIError. Die Beispiele verwenden den client aus Client erstellen. app_id ist die ID einer deiner Apps: client.account.me() listet sie auf.

from squarecloud import SquareCloudAPIError

try:
    client.apps.start(app_id)
except SquareCloudAPIError as error:
    print(error.status, error.code, error.message)
    print(error.method, error.path)  # "POST" "/v2/apps/<id>/start"
    print(error)  # POST /v2/apps/<id>/start: HTTP 404 APP_NOT_FOUND

`SquareCloudAPIError`

SquareCloudAPIError ist eine Unterklasse von Exception.

Attribut	Typ	Beschreibung
`status`	`int`	HTTP-Status. `0`, wenn keine Antwort eingetroffen ist (Netzwerkfehler, Timeout, lokale Prüfung)
`code`	`str`	Der Fehlercode der API, z. B. `APP_NOT_FOUND`, oder einer der Codes des SDK
`message`	`str`	Die Erklärung des Servers. `''`, wenn der Server nur einen Code gesendet hat
`method`	`str`	HTTP-Methode des fehlgeschlagenen Aufrufs
`path`	`str`	URL-Pfad des fehlgeschlagenen Aufrufs, ohne den Query-String
`cause`	`BaseException \| None`	Die ursprüngliche Exception, bei `NETWORK_ERROR`, `TIMEOUT` und ungültigem JSON (dieselbe wie `__cause__`)

str(error) lautet <METHOD> <path>: HTTP <status> <CODE>: <message>, ohne HTTP <status>, wenn der Status 0 ist, und ohne : <message>, wenn die Nachricht leer ist. Zwei Fehler werden nicht verpackt:

Ein leerer oder nur aus Leerzeichen bestehender API-Schlüssel wirft im Konstruktor des Clients einen ValueError.
Lokale Dateiprobleme werfen einen OSError: ein Upload-Pfad, der sich nicht öffnen lässt, eine Datei, die während des Uploads unlesbar wird, oder ein Ziel von download_snapshot, das sich nicht schreiben lässt.

Codes des SDK

Status	Code	Wann
0	`NETWORK_ERROR`	Keine Antwort (DNS, Verbindung zurückgesetzt, Body abgeschnitten). Die ursprüngliche Exception steht in `cause`
0	`TIMEOUT`	Eine Socket-Operation hat das Timeout überschritten
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 des Servers oder `HTTP <status>`, wenn es keine gibt. Ein 2xx-Body, der kein JSON ist, hat die Nachricht `Invalid JSON in HTTP <status> response`

Codes sind Strings

code ist ein einfacher str: Das SDK hat kein Enum für Codes. Der Docstring von SquareCloudAPIError listet jeden bekannten API-Code auf. RATE_LIMIT und RATE_LIMIT_EXCEEDED sind dort weiterhin aufgeführt 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:

def start(app_id: str):
    try:
        client.apps.start(app_id)
    except SquareCloudAPIError as error:
        match error.code:
            case "APP_NOT_FOUND":
                return None
            case "CONTAINER_ALREADY_STARTED":
                return  # fine
            case _:
                if error.status == 429:
                    return retry_later()
                if error.status >= 500:
                    return report_outage(error)
                raise

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 max_retries 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 max_retries=0, um Wiederholungen abzuschalten.

Timeouts

timeout (30 s) gilt pro Socket-Operation (der Verbindungsaufbau und jedes Lesen oder Schreiben), nicht für die gesamte Anfrage. 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.

CLI

VS Code

SDKs

Python-SDK: Fehler und Wiederholungen

`SquareCloudAPIError`

Codes des SDK

Codes sind Strings

API-Fehlercodes

Wiederholungen

Timeouts

Rate Limits

Nächste Schritte

Referenz der API-Fehler

Limits und Beschränkungen

​SquareCloudAPIError

​Codes des SDK

​Codes sind Strings

​API-Fehlercodes

​Wiederholungen

​Timeouts

​Rate Limits

​Nächste Schritte

Referenz der API-Fehler

Limits und Beschränkungen

`SquareCloudAPIError`

Codes des SDK

Codes sind Strings

API-Fehlercodes

Wiederholungen

Timeouts

Rate Limits

Nächste Schritte