*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 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. 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 401ACCESS_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, 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: 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 deAccount.Snapshots. - 429
KEEP_CALM: demasiadas llamadas a una misma ruta en poco tiempo.
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.

