Skip to main content
v6 ist eine Neuentwicklung: ein flacher Client, einfache Daten statt Klassen, IDs als erstes Argument und eine einzige Fehlerklasse. Die meisten Änderungen sind mechanisch.

Auf einen Blick

Konstruktion und Optionen

Methode für Methode

Typen

Die Typen sind im SDK enthalten und spiegeln die Feldnamen der API wider. Die wichtigsten Umbenennungen gegenüber @squarecloud/api-types und den Klassen von v5:

Fehler

  • Synthetische Codes gibt es nicht mehr (RATE_LIMIT_EXCEEDED, PAYLOAD_TOO_LARGE, SERVER_UNAVAILABLE, UNKNOWN_ERROR_<status>): Der echte Code der API kommt durch (RATE_LIMITED, KEEP_CALM, DAILY_SNAPSHOTS_LIMIT_REACHED, FILE_TOO_LARGE…).
  • Keine Antwort: status: 0 mit NETWORK_ERROR (die Ursache in cause) oder TIMEOUT. Ein Body ohne Code ist UNKNOWN_ERROR mit dem echten status und der Nachricht HTTP <status>.
  • instanceof TypeError ist für API-Fehler nicht mehr wahr.
  • Ein abgelaufener Schlüssel ergibt 401 ACCESS_DENIED, wie ein unbekannter.
  • Fehler von ai.chat(), einschließlich Authentifizierung und Rate Limits, tragen den kleingeschriebenen OpenAI-Code (access_denied, rate_limit_exceeded, …).
  • Ein abgelehntes start/stop/restart ergibt 409 nur mit einem Code: CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_TEMPORARILY_SUSPENDED, CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT oder ACTION_FAILED.

Verhaltensänderungen

  • Aufrufe haben ein Timeout: standardmäßig 30 s pro Versuch (v5 hatte keins), mindestens 120 s für Aufrufe, die der Server offen hält. Setze timeoutMs: 0 für keins.
  • files.write() behandelt einen String als Inhalt und sendet ihn als reinen Text; Bytes gehen als Base64, binärsicher, und leerer Inhalt erstellt eine leere Datei (dasselbe Übertragungsformat wie bei den SDKs für Python und Go). files.read() fordert Base64 an und dekodiert es.
  • files.list() eines fehlenden Verzeichnisses wirft 404 FILE_NOT_FOUND, statt [] zurückzugeben.
  • snapshots.create() gibt bei 202 { pending: true } zurück, statt einen Fehler zu werfen.
  • String-Ergebnisse sind nie undefined: setWebhook und resetCredentials("certificate") geben "" zurück, wenn die API keines sendet; deploys.current() gibt {} zurück.
  • realtime() verbindet sich bei abgebrochenen Verbindungen und bei REALTIME_RECONNECT neu (bis zu 3 Mal hintereinander, höchstens ein Öffnen pro 5,5 s).
  • Wiederholungen: Netzwerkfehler bei GET und 503 UPLOAD_BUSY/ANALYTICS_BUSY (plus DATABASE_UNAVAILABLE bei GET), mit Backoff. 429 wird nie wiederholt. DATABASE_UNAVAILABLE kann eintreffen, nachdem eine Mutation angewendet wurde: Wiederhole deine idempotenten Mutationen selbst.
  • Leere IDs sowie . und .. schlagen lokal mit INVALID_ID fehl.
  • Query-Werte, die undefined, "" oder false sind, werden nicht gesendet.