Skip to main content
Todo fallo de la API, de red o local es un único tipo: *squarecloud.APIError. Inspecciónalo con errors.As. Los fragmentos más cortos de abajo se ejecutan dentro del programa de Ejecutar los ejemplos: pega uno a la vez en main y ejecuta goimports.

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. CodeRateLimit (RATE_LIMIT) y CodeRateLimitExceeded (RATE_LIMIT_EXCEEDED) se siguen exportando, marcados como obsoletos: la API ahora responde RATE_LIMITED (CodeRateLimited) para ambos. La lista de códigos de la API crece. Gestiona un código desconocido por su estado HTTP:

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, …), 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: 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

Referencia de errores de la API

Cada código de error, con su significado y cómo resolverlo.

Límites y restricciones

Los límites de solicitudes de cada plan.