Skip to main content
La v6 est une réécriture : un client plat unique, des données brutes au lieu de classes, les identifiants en premier argument et une seule classe d’erreur. La plupart des changements sont mécaniques.

En un coup d’œil

Construction et options

Méthode par méthode

Types

Les types sont livrés avec le SDK et reprennent les noms de champs de l’API. Les principaux renommages depuis @squarecloud/api-types et les classes de la v5 :

Erreurs

  • Les codes synthétiques ont disparu (RATE_LIMIT_EXCEEDED, PAYLOAD_TOO_LARGE, SERVER_UNAVAILABLE, UNKNOWN_ERROR_<status>) : c’est le vrai code de l’API qui remonte (RATE_LIMITED, KEEP_CALM, DAILY_SNAPSHOTS_LIMIT_REACHED, FILE_TOO_LARGE…).
  • Aucune réponse : status: 0 avec NETWORK_ERROR (la cause dans cause) ou TIMEOUT. Un corps sans code donne UNKNOWN_ERROR avec le vrai status et le message HTTP <status>.
  • instanceof TypeError n’est plus vrai pour les erreurs de l’API.
  • Une clé expirée donne 401 ACCESS_DENIED, comme une clé inconnue.
  • Les erreurs de ai.chat(), authentification et limites de débit comprises, portent le code OpenAI en minuscules (access_denied, rate_limit_exceeded, …).
  • Un start/stop/restart refusé donne 409 avec uniquement un code : CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_TEMPORARILY_SUSPENDED, CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT ou ACTION_FAILED.

Changements de comportement

  • Les appels expirent : 30 s par tentative par défaut (la v5 n’avait pas de timeout), au moins 120 s pour les appels que le serveur maintient ouverts. Définissez timeoutMs: 0 pour n’en avoir aucun.
  • files.write() traite une chaîne comme le contenu et l’envoie en texte brut ; les octets partent en base64, sans perte pour le binaire, et un contenu vide crée un fichier vide (même format de transmission que les SDKs Python et Go). files.read() demande du base64 et le décode.
  • files.list() sur un répertoire manquant lève 404 FILE_NOT_FOUND au lieu de renvoyer [].
  • snapshots.create() renvoie { pending: true } sur un 202 au lieu de lever une erreur.
  • Les résultats de type chaîne ne sont jamais undefined : setWebhook et resetCredentials("certificate") renvoient "" quand l’API n’envoie rien ; deploys.current() renvoie {}.
  • realtime() se reconnecte en cas de connexion interrompue et sur REALTIME_RECONNECT (jusqu’à 3 fois d’affilée, au plus une ouverture toutes les 5,5 s).
  • Nouvelles tentatives : erreurs réseau sur GET et 503 UPLOAD_BUSY/ANALYTICS_BUSY (plus DATABASE_UNAVAILABLE sur GET), avec backoff. Un 429 n’est jamais réessayé. DATABASE_UNAVAILABLE peut survenir après l’application d’une mutation : réessayez vous-même vos mutations idempotentes.
  • Les identifiants vides, . et .. échouent localement avec INVALID_ID.
  • Les valeurs de requête undefined, "" ou false ne sont pas envoyées.