> ## Documentation Index > Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt > Use this file to discover all available pages before exploring further. # SDK de JavaScript: errores y reintentos > Gestiona SquareCloudAPIError en @squarecloud/api: estado, código y mensaje, los códigos de error propios del SDK, reintentos, timeouts y límites de tasa. Todo fallo de la API, de red o local lanza una única clase: `SquareCloudAPIError`. Los ejemplos usan el cliente `api` de [Crear el cliente](/es/sdks/js/client#crear-el-cliente). `appId` es el id de una de tus aplicaciones: [`api.account.me()`](/es/sdks/js/client#cuenta) las lista. ```typescript theme={"system"} 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//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](/es/sdks/js/client#timeouts) | | 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 `. Un cuerpo 2xx que no es JSON tiene el mensaje `Invalid JSON in HTTP 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**: ```typescript theme={"system"} 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](/es/api-reference/errors) 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](/es/sdks/js/client#clave-de-api-y-scopes)), 429 (consulta [Límites de tasa](#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](/es/sdks/js/ai#errores). ## 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](/es/sdks/js/client#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](/es/api-reference/limitations-and-restrictions)), 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. ## Próximos pasos Cada código de error, con su significado y cómo resolverlo. Los límites de solicitudes de cada plan. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.