SDK de JavaScript: errores y reintentos

Todo fallo de la API, de red o local lanza una única clase: SquareCloudAPIError. Los ejemplos usan el cliente api de Crear el cliente. appId es el id de una de tus aplicaciones: api.account.me() las lista.

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/<id>/start"
    }
}

`SquareCloudAPIError`

SquareCloudAPIError extiende Error (no es un TypeError).

Propiedad	Tipo	Descripción
`status`	`number`	Estado HTTP. `0` cuando no llegó ninguna respuesta (error de red, timeout, comprobación local)
`code`	`ErrorCode`	El código de error de la API, p. ej. `APP_NOT_FOUND`, o uno de los códigos del SDK
`message`	`string`	La explicación del servidor. Cuando el servidor solo envió un código, el propio código
`method`	`string`	Método HTTP de la llamada fallida
`path`	`string`	Ruta de la URL de la llamada fallida, sin la query string
`cause`	`unknown`	El error original, para `NETWORK_ERROR` y JSON no válido

Hay dos fallos que no se envuelven:

Una llamada abortada se rechaza con el reason del signal. Un bucle de realtime() abortado simplemente termina.
Una ruta de subida que no se puede abrir lanza el error del sistema de archivos.

Códigos del SDK

Estado	Código	Cuándo
0	`NETWORK_ERROR`	Sin respuesta (DNS, conexión reiniciada, cuerpo cortado). El error original está en `cause`
0	`TIMEOUT`	Sin respuesta dentro del timeout
0	`FILE_TOO_LARGE`	Comprobación local: una subida de más de 100 MB o un `files.write` de más de 10 MB. No se envió nada
0	`INVALID_ID`	Comprobación local: un id vacío, `.` o `..`. No se envió nada
cualquiera	`UNKNOWN_ERROR`	Una respuesta sin código (como la página de error de un proxy), con el `status` real y el mensaje `HTTP <status>`. Un cuerpo 2xx que no es JSON tiene el mensaje `Invalid JSON in HTTP <status> response`

El tipo `ErrorCode`

ErrorCode es solo un tipo (no hay ningún objeto en tiempo de ejecución). Enumera todos los códigos públicos de la API, los obsoletos y los del SDK, además de string & {}, de modo que tu editor autocompleta los códigos conocidos y los códigos nuevos siguen pasando la comprobación de tipos. RATE_LIMIT y RATE_LIMIT_EXCEEDED siguen en el tipo, marcados como obsoletos: la API ahora responde RATE_LIMITED para ambos. La lista de códigos de la API crece. Gestiona un código desconocido por su estado HTTP:

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;
        }
    }
}

Códigos de error de la API

Todos los demás códigos vienen de la API. La referencia de errores de la API enumera cada uno con su estado HTTP, su significado y cómo resolverlo, y cada página del SDK enumera los códigos que sus métodos devuelven con más frecuencia. Cualquier llamada también puede responder 401 ACCESS_DENIED (una clave incorrecta), 403 MISSING_SCOPE o RESOURCE_NOT_ALLOWED (los límites de la clave), 429 (consulta Límites de tasa) o 503 DATABASE_UNAVAILABLE. Los errores de ai.chat() usan en cambio códigos de OpenAI en minúsculas (access_denied, rate_limit_exceeded, server_overloaded, …). Consulta IA.

Reintentos

El SDK solo reintenta lo que es seguro repetir, hasta maxRetries veces (por defecto 2, es decir, hasta 3 intentos):

Se reintenta	Métodos
`NETWORK_ERROR`	Solo `GET`
503 `UPLOAD_BUSY`	Cualquier método
503 `ANALYTICS_BUSY`	Cualquier método
503 `DATABASE_UNAVAILABLE`	Solo `GET`

Nunca reintenta:

TIMEOUT;
ningún 429: RATE_LIMITED puede ser un bloqueo de unos 30 minutos, y KEEP_CALM tampoco se reintenta;
otros 5xx;
los errores de IA.

Un 503 DATABASE_UNAVAILABLE puede llegar después de que una mutación ya se haya aplicado, así que el SDK no lo reintenta fuera de GET. Reintenta tú mismo tus mutaciones idempotentes si lo necesitas. La espera antes del reintento n (empezando en 0) es min(8 s, 500 ms · 2^n) · U(0.5, 1): backoff exponencial con un jitter del 50% al 100%. Establece maxRetries: 0 para desactivar los reintentos.

Timeouts

timeoutMs (30 s) se aplica por intento y cubre toda la respuesta. Consulta Timeouts para ver las llamadas con un mínimo de 120 s y las llamadas sin timeout. Un timeout lanza TIMEOUT con estado 0 y nunca se reintenta.

Límites de tasa

Cada cuenta tiene un límite de peticiones cada 60 segundos, fijado por su plan (valores), y algunas rutas tienen el suyo propio:

429 RATE_LIMITED: la cuenta o la clave de API superó su cupo de solicitudes y queda bloqueada durante unos 30 minutos, o una IP que sigue enviando claves inválidas queda bloqueada durante un periodo breve. También es el límite de los endpoints de red y de account.snapshots.
429 KEEP_CALM: demasiadas llamadas a una misma ruta en poco tiempo.

El SDK nunca reintenta un 429. Reduce el ritmo y espera antes de volver a intentarlo.

CLI

VS Code

SDKs

SDK de JavaScript: errores y reintentos

`SquareCloudAPIError`

Códigos del SDK

El tipo `ErrorCode`

Códigos de error de la API

Reintentos

Timeouts

Límites de tasa

Próximos pasos

Referencia de errores de la API

Límites y restricciones

​SquareCloudAPIError

​Códigos del SDK

​El tipo ErrorCode

​Códigos de error de la API

​Reintentos

​Timeouts

​Límites de tasa

​Próximos pasos

Referencia de errores de la API

Límites y restricciones

`SquareCloudAPIError`

Códigos del SDK

El tipo `ErrorCode`

Códigos de error de la API

Reintentos

Timeouts

Límites de tasa

Próximos pasos