SDK de JavaScript: migrar de v5 a v6

​

De un vistazo

​

Construcción y opciones

​

Método por método

​

Tipos

​

Errores

// v5
catch (e) { if (e.code === "RATE_LIMIT_EXCEEDED") ... }

// v6
catch (e) {
  if (e instanceof SquareCloudAPIError && e.status === 429) {
    console.log(e.code, e.message); // KEEP_CALM "Please wait 5 seconds..." or RATE_LIMITED
  }
}

• Los códigos sintéticos desaparecen (RATE_LIMIT_EXCEEDED, PAYLOAD_TOO_LARGE, SERVER_UNAVAILABLE, UNKNOWN_ERROR_<status>): aparece el código real de la API (RATE_LIMITED, KEEP_CALM, DAILY_SNAPSHOTS_LIMIT_REACHED, FILE_TOO_LARGE…).
• Sin respuesta: status: 0 con NETWORK_ERROR (la causa en cause) o TIMEOUT. Un cuerpo sin código es UNKNOWN_ERROR con el status real y el mensaje HTTP <status>.
• instanceof TypeError ya no es verdadero para los errores de la API.
• Una clave caducada da 401 ACCESS_DENIED, igual que una desconocida.
• Los errores de ai.chat(), incluidos los de autenticación y límites de tasa, llevan el código de OpenAI en minúsculas (access_denied, rate_limit_exceeded, …).
• Un start/stop/restart rechazado es un 409 con solo un código: CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_TEMPORARILY_SUSPENDED, CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT o ACTION_FAILED.

​

Cambios de comportamiento

• Las llamadas tienen timeout: 30 s por intento por defecto (la v5 no tenía timeout), al menos 120 s para las llamadas que el servidor mantiene abiertas. Establece timeoutMs: 0 para no tener ninguno.
• files.write() trata un string como el contenido y lo envía como texto plano; los bytes van en base64, de forma segura para binarios, y un contenido vacío crea un archivo vacío (el mismo formato de envío que los SDKs de Python y Go). files.read() pide base64 y lo decodifica.
• files.list() de un directorio inexistente lanza 404 FILE_NOT_FOUND en lugar de devolver [].
• snapshots.create() devuelve { pending: true } en un 202 en lugar de lanzar un error.
• Los resultados de tipo string nunca son undefined: setWebhook y resetCredentials("certificate") devuelven "" cuando la API no envía nada; deploys.current() devuelve {}.
• realtime() se reconecta cuando se cae la conexión y con REALTIME_RECONNECT (hasta 3 veces seguidas, como máximo una apertura cada 5,5 s).
• Reintentos: errores de red en GET y 503 UPLOAD_BUSY/ANALYTICS_BUSY (más DATABASE_UNAVAILABLE en GET), con backoff. Un 429 nunca se reintenta. DATABASE_UNAVAILABLE puede llegar después de que se haya aplicado una mutación: reintenta tú mismo tus mutaciones idempotentes.
• Los ids vacíos, . y .. fallan localmente con INVALID_ID.
• Los valores de query que son undefined, "" o false no se envían.

​

Próximos pasos