*squarecloud.APIError. Inspecciónalo con errors.As.
APIError
Unwrap() devuelve la causa (el error de transporte, de decodificación o del context) para NETWORK_ERROR, TIMEOUT y el JSON no válido, o nil. Error() produce squarecloud: <METHOD> <path>: HTTP <status> <CODE>: <message>, sin HTTP <status> cuando el estado es 0 y sin : <message> cuando está vacío. Compara los campos, no este texto.
Contexts cancelados y caducados
Una llamada cuyoctx se cancela devuelve un *APIError con NETWORK_ERROR, y una cuyo deadline pasa devuelve TIMEOUT, ambos con estado 0. Ambos envuelven el error del context:
*APIError:
Realtime.Nextdevuelve elctx.Err()sin envolver cuando suctxtermina, eio.EOFcuando el stream termina con normalidad.- Los problemas del lado del llamador son errores simples: un reader de subida
nil, una URL de snapshot o una URL base que no se puede analizar, una entrada queencoding/jsonno puede codificar y un error delio.Writerque se pasa aDownloadSnapshot.
Códigos del SDK
Constantes Code*
Code es un string simple. El paquete tiene una constante por cada código público de la API, con su nombre en estilo Go (CodeAppNotFound para APP_NOT_FOUND, CodeInvalidID, CodeDNSFailed, …), además de los códigos propios del SDK indicados arriba.
La lista de códigos de la API crece. Gestiona un código desconocido por su estado HTTP:
Errores de cualquier llamada
Códigos de la API por grupo
No encontrado
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_FOUNDValidación
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_SUPPORTEDAutenticación y permisos
Autenticación y permisos
ACCESS_DENIED, MISSING_SCOPE, RESOURCE_NOT_ALLOWED, PERMISSION_DENIED, SCOPE_NOT_GRANTABLE, BLOCKED_PATH, UPGRADE_REQUIREDLímites y límites de tasa
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_REACHEDContenedores (iniciar, detener, reiniciar)
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_RUNNINGSubidas, archivos y commits
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_RESPONSESnapshots
Snapshots
SNAPSHOT_FAILED, SNAPSHOT_PROCESSING, SNAPSHOT_RESTORE_FAILED, SNAPSHOT_DATABASE_MISMATCH, RESTORE_IN_PROGRESSDeploys y GitHub
Deploys y GitHub
GIT_ALREADY_CONFIGURED, GIT_NOT_CONFIGURED, GITHUB_NOT_CONNECTED, REPOSITORY_BRANCH_ALREADY_CONFIGURED, REPOSITORY_NOT_AVAILABLE, REPOSITORY_PERMISSION_REQUIRED, FAILED_TO_FETCHRed y dominios
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_SUPPORTEDBases de datos y workspaces
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_RESOURCESPlataforma
Plataforma
INTERNAL_SERVER_ERROR, CLUSTER_MAINTENANCE_TRY_LATER, CLUSTER_SELECTION_FAILED, CLUSTER_TIMEOUT, CLUSTER_UNAVAILABLE, AI_UNAVAILABLEObsoletos
Obsoletos
CodeRateLimit (RATE_LIMIT) y CodeRateLimitExceeded (RATE_LIMIT_EXCEEDED) se siguen exportando, marcados como obsoletos: ahora la API responde RATE_LIMITED (CodeRateLimited) en ambos casos.AI.Chat usan en cambio códigos de OpenAI en minúsculas (access_denied, rate_limit_exceeded, server_overloaded, …), que Code contiene tal cual. Consulta IA.
Reintentos
El SDK solo reintenta lo que es seguro repetir, hastaWithMaxRetries veces (por defecto 2, es decir, hasta 3 intentos):
Nunca reintenta:
TIMEOUT;- ningún 429:
RATE_LIMITEDpuede ser un bloqueo de unos 30 minutos, yKEEP_CALMtampoco se reintenta; - otros 5xx;
- los errores de IA.
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. Una subida solo se reintenta cuando su cuerpo se puede reproducir de nuevo: un io.ReaderAt de tamaño conocido, como un *os.File (consulta Commit y subida).
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 WithMaxRetries(0) para desactivar los reintentos.
Timeouts
WithTimeout (30 s) solo se aplica cuando ctx no tiene deadline, y un único deadline cubre toda la llamada, reintentos y esperas de backoff incluidos. Consulta Timeouts para ver las llamadas con un mínimo de 2 minutos y las llamadas sin deadline por defecto. Un deadline que se supera devuelve TIMEOUT con estado 0, nunca se reintenta y envuelve context.DeadlineExceeded.
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 deAccount.Snapshots. - 429
KEEP_CALM: demasiadas llamadas a una misma ruta en poco tiempo.

