SDK de Python: errores y reintentos

Todo fallo de la API o de red lanza una única excepción: SquareCloudAPIError. Los ejemplos usan el client de Crear el cliente. app_id es el id de una de tus aplicaciones: client.account.me() las lista.

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. RATE_LIMIT y RATE_LIMIT_EXCEEDED siguen en esa lista, 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:

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

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 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: 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 Python: errores y reintentos

`SquareCloudAPIError`

Códigos del SDK

Los códigos son strings

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

​Los códigos son strings

​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

Los códigos son strings

Códigos de error de la API

Reintentos

Timeouts

Límites de tasa

Próximos pasos