Skip to main content
Todo fallo de la API, de red o local es un único tipo: *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 cuyo ctx 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:
Algunos fallos no son *APIError:
  • Realtime.Next devuelve el ctx.Err() sin envolver cuando su ctx termina, e io.EOF cuando 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 que encoding/json no puede codificar y un error del io.Writer que se pasa a DownloadSnapshot.

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

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
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
ACCESS_DENIED, MISSING_SCOPE, RESOURCE_NOT_ALLOWED, PERMISSION_DENIED, SCOPE_NOT_GRANTABLE, BLOCKED_PATH, UPGRADE_REQUIRED
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
CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_TEMPORARILY_SUSPENDED, CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT, ACTION_FAILED, DATABASE_NOT_RUNNING
UPLOAD_BUSY, UPLOAD_FAILED, UPLOAD_ABORTED, STORAGE_UPLOAD_FAILED, COMMIT_FAILED, READ_FAILED, SAVE_FAILED, RENAME_FAILED, DELETE_FAILED, REQUEST_ABORTED, EMPTY_RESPONSE
SNAPSHOT_FAILED, SNAPSHOT_PROCESSING, SNAPSHOT_RESTORE_FAILED, SNAPSHOT_DATABASE_MISMATCH, RESTORE_IN_PROGRESS
GIT_ALREADY_CONFIGURED, GIT_NOT_CONFIGURED, GITHUB_NOT_CONNECTED, REPOSITORY_BRANCH_ALREADY_CONFIGURED, REPOSITORY_NOT_AVAILABLE, REPOSITORY_PERMISSION_REQUIRED, FAILED_TO_FETCH
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
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
INTERNAL_SERVER_ERROR, CLUSTER_MAINTENANCE_TRY_LATER, CLUSTER_SELECTION_FAILED, CLUSTER_TIMEOUT, CLUSTER_UNAVAILABLE, AI_UNAVAILABLE
CodeRateLimit (RATE_LIMIT) y CodeRateLimitExceeded (RATE_LIMIT_EXCEEDED) se siguen exportando, marcados como obsoletos: ahora la API responde RATE_LIMITED (CodeRateLimited) 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, …), que Code contiene tal cual. Consulta IA.

Reintentos

El SDK solo reintenta lo que es seguro repetir, hasta WithMaxRetries veces (por defecto 2, es decir, hasta 3 intentos): 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. 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 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.