Errores

Todo fallo de la API o de red lanza una única excepción: SquareCloudAPIError.

from squarecloud import SquareCloudAPIError

try:
    client.apps.start(app_id)
except SquareCloudAPIError as error:
    print(error.status, error.code, error.message)
    print(error.method, error.path)  # "POST" "/v2/apps/<id>/start"
    print(error)  # POST /v2/apps/<id>/start: HTTP 404 APP_NOT_FOUND

`SquareCloudAPIError`

SquareCloudAPIError es una subclase de Exception.

Atributo	Tipo	Descripción
`status`	`int`	Estado HTTP. `0` cuando no llegó ninguna respuesta (error de red, timeout, comprobación local)
`code`	`str`	El código de error de la API, p. ej. `APP_NOT_FOUND`, o uno de los códigos del SDK
`message`	`str`	La explicación del servidor. `''` cuando el servidor solo envió un código
`method`	`str`	Método HTTP de la llamada fallida
`path`	`str`	Ruta de la URL de la llamada fallida, sin la query string
`cause`	`BaseException \| None`	La excepción original, para `NETWORK_ERROR`, `TIMEOUT` y JSON no válido (la misma que `__cause__`)

str(error) es <METHOD> <path>: HTTP <status> <CODE>: <message>, sin HTTP <status> cuando el estado es 0 y sin : <message> cuando el mensaje está vacío. Hay dos fallos que no se envuelven:

Una clave de API vacía o compuesta solo por espacios lanza un ValueError en el constructor del cliente.
Los problemas con archivos locales lanzan un OSError: una ruta de subida que no se puede abrir, un archivo que deja de poder leerse a mitad de la subida o un destino de download_snapshot en el que no se puede escribir.

Códigos del SDK

Estado	Código	Cuándo
0	`NETWORK_ERROR`	Sin respuesta (DNS, conexión reiniciada, cuerpo cortado). La excepción original está en `cause`
0	`TIMEOUT`	Una operación de socket superó el 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 del servidor, o `HTTP <status>` cuando no hay ninguno. Un cuerpo 2xx que no es JSON tiene el mensaje `Invalid JSON in HTTP <status> response`

Los códigos son strings

code es un str normal: el SDK no tiene ningún enum de códigos. El docstring de SquareCloudAPIError enumera todos los códigos conocidos de la API, y los grupos de abajo también los enumeran. La lista de códigos de la API crece. Gestiona un código desconocido por su estado HTTP:

def start(app_id: str):
    try:
        client.apps.start(app_id)
    except SquareCloudAPIError as error:
        match error.code:
            case "APP_NOT_FOUND":
                return None
            case "CONTAINER_ALREADY_STARTED":
                return  # fine
            case _:
                if error.status == 429:
                    return retry_later()
                if error.status >= 500:
                    return report_outage(error)
                raise

Errores de cualquier llamada

Estado	Código	Cuándo
401	`ACCESS_DENIED`	Clave de API ausente, desconocida, revocada o caducada
403	`MISSING_SCOPE`	A la clave le falta el scope de esta llamada. `message` lo indica
403	`RESOURCE_NOT_ALLOWED`	La clave está limitada a otras aplicaciones o bases de datos
403	`PERMISSION_DENIED`	Tu rol en el workspace no permite la acción
404	`ROUTE_NOT_FOUND`	Ruta desconocida
429	`RATE_LIMITED`	Bloqueo de la cuenta, la clave o la IP (puede durar unos 30 min), y el límite de los endpoints de red y de `account.snapshots`
429	`KEEP_CALM`	Demasiado rápido para esta ruta
500	`INTERNAL_SERVER_ERROR`	Error del servidor
503	`DATABASE_UNAVAILABLE`	La base de datos de la plataforma no está disponible. Es posible que una mutación ya se haya aplicado

Códigos de la API por grupo

No encontrado

APP_NOT_FOUND, DATABASE_NOT_FOUND, WORKSPACE_NOT_FOUND, MEMBER_NOT_FOUND, FILE_NOT_FOUND, SNAPSHOT_NOT_FOUND, REPOSITORY_NOT_FOUND, BRANCH_NOT_FOUND, ROUTE_NOT_FOUND

Validación

INVALID_ACCESS_TOKEN, INVALID_AUTORESTART, INVALID_BRANCH_LENGTH, INVALID_CODE, INVALID_CONTENT, INVALID_CONTENT_TYPE, INVALID_DATABASE_TYPE, INVALID_DATABASE_VERSION, INVALID_DESCRIPTION, INVALID_DISPLAY_NAME, INVALID_DOMAIN, INVALID_ENCODING, INVALID_ENV_CONTENT, INVALID_FILE, INVALID_FILENAME, INVALID_FILTER, INVALID_GROUP, INVALID_ID, INVALID_INPUT, INVALID_JSON_BODY, INVALID_MEMORY, INVALID_NAME, INVALID_PARAMETERS, INVALID_PATH, INVALID_RESET_TYPE, INVALID_SCOPE, INVALID_SNAPSHOT_ID, INVALID_SUBDOMAIN, INVALID_TIME_RANGE, INVALID_VERSION_ID, MISSING_PARAMETERS, MISSING_REQUIRED_FIELDS, NO_UPDATE_DATA, VALIDATION_FAILED, VALIDATION_TIMEOUT, ENV_NAME_TOO_LONG, ENV_CONTENT_TOO_LONG, TOO_MANY_ENV_VARS, RESERVED_DOMAIN, CANNOT_SET_SUBDOMAIN, STATIC_APP_ENV_NOT_SUPPORTED

Autenticación y permisos

ACCESS_DENIED, MISSING_SCOPE, RESOURCE_NOT_ALLOWED, PERMISSION_DENIED, SCOPE_NOT_GRANTABLE, BLOCKED_PATH, UPGRADE_REQUIRED

Límites y límites de tasa

RATE_LIMITED, KEEP_CALM, APPLICATIONS_LIMIT_REACHED, WORKSPACE_LIMIT_REACHED, MEMBERS_LIMIT_REACHED, LOAD_BALANCER_LIMIT_REACHED, DAILY_SNAPSHOTS_LIMIT_REACHED, INSUFFICIENT_MEMORY, FILE_TOO_LARGE, PAYLOAD_TOO_LARGE, REALTIME_MAX_CONNECTIONS, REALTIME_MAX_CONNECTIONS_APP, AI_DAILY_LIMIT_REACHED, AI_MAX_CONCURRENT_STREAMS, AI_NO_PLAN_LIMIT_REACHED

Contenedores (iniciar, detener, reiniciar)

CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_TEMPORARILY_SUSPENDED, CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT, ACTION_FAILED, DATABASE_NOT_RUNNING

Subidas, archivos y commits

UPLOAD_BUSY, UPLOAD_FAILED, UPLOAD_ABORTED, STORAGE_UPLOAD_FAILED, COMMIT_FAILED, READ_FAILED, SAVE_FAILED, RENAME_FAILED, DELETE_FAILED, REQUEST_ABORTED, EMPTY_RESPONSE

Snapshots

SNAPSHOT_FAILED, SNAPSHOT_PROCESSING, SNAPSHOT_RESTORE_FAILED, SNAPSHOT_DATABASE_MISMATCH, RESTORE_IN_PROGRESS

Deploys y GitHub

GIT_ALREADY_CONFIGURED, GIT_NOT_CONFIGURED, GITHUB_NOT_CONNECTED, REPOSITORY_BRANCH_ALREADY_CONFIGURED, REPOSITORY_NOT_AVAILABLE, REPOSITORY_PERMISSION_REQUIRED, FAILED_TO_FETCH

Red y dominios

ANALYTICS_BUSY, UNABLE_TO_FETCH_ANALYTICS, UNABLE_TO_FETCH_ERRORS, UNABLE_TO_FETCH_PERFORMANCE, DNS_FAILED, DOMAIN_ALREADY_EXISTS, NO_CUSTOM_DOMAIN, PURGE_CACHE_FAILED, LOGS_UNAVAILABLE, METRICS_NOT_SUPPORTED

Bases de datos y workspaces

DATABASE_CREATION_FAILED, DATABASE_UNAVAILABLE, RESET_FAILED, WORKSPACE_CREATION_FAILED, APP_ALREADY_IN_WORKSPACE, MEMBER_ALREADY_ADDED, CANNOT_EDIT_OWNER, CANNOT_INVITE_OWNER, CANNOT_LEAVE_OWNER, CONFLICTING_RESOURCES

Plataforma

INTERNAL_SERVER_ERROR, CLUSTER_MAINTENANCE_TRY_LATER, CLUSTER_SELECTION_FAILED, CLUSTER_TIMEOUT, CLUSTER_UNAVAILABLE, AI_UNAVAILABLE

Obsoletos

RATE_LIMIT y RATE_LIMIT_EXCEEDED siguen en la lista, marcados como obsoletos: ahora la API responde RATE_LIMITED en ambos casos.

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 max_retries 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 max_retries=0 para desactivar los reintentos.

Timeouts

timeout (30 s) se aplica por operación de socket (la conexión y cada lectura o escritura), no a toda la petición. 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: un bloqueo de la cuenta, la clave de API o la IP, que puede durar unos 30 minutos. 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.

Servicios

Runtimes

Plataforma

Solución de problemas

CLI

SDKs

Changelog

`SquareCloudAPIError`

Códigos del SDK

Los códigos son strings

Errores de cualquier llamada

Códigos de la API por grupo

Reintentos

Timeouts

Límites de tasa

​SquareCloudAPIError

​Códigos del SDK

​Los códigos son strings

​Errores de cualquier llamada

​Códigos de la API por grupo

​Reintentos

​Timeouts

​Límites de tasa

`SquareCloudAPIError`

Códigos del SDK

Los códigos son strings

Errores de cualquier llamada

Códigos de la API por grupo

Reintentos

Timeouts

Límites de tasa