Skip to main content
Cada solicitud fallida a la API de Square Cloud responde con un estado HTTP y un cuerpo JSON que incluye un code legible por máquina. Esta página lista todos los códigos, agrupados por área. La página de cada endpoint también lista los códigos que ese endpoint devuelve con más frecuencia.
Blob Storage tiene su propia lista de códigos, y el AI Gateway responde en el formato de error de OpenAI con códigos en minúsculas. Ninguno de los dos se cubre aquí.

Formato del error

La lista de códigos crece con el tiempo. Trata un código que no conoces como un fallo genérico del estado HTTP con el que llegó: corrige la solicitud ante un 4xx, espera ante un 429 y vuelve a intentarlo más tarde ante un 5xx.

Reintentos

La API no envía el encabezado Retry-After, así que la decisión es tuya. Una política segura: 202 SNAPSHOT_PROCESSING mantiene el formato de error por compatibilidad, pero no es un fallo: el snapshot aún se está generando y aparecerá en el listado por sí solo. No lo vuelvas a solicitar.

Límites de tasa

Dos códigos responden 429, y significan cosas distintas:
  • RATE_LIMITED: el presupuesto de solicitudes de tu cuenta o de tu clave de API, contado por cada 60 segundos y definido por tu plan (consulta los valores por plan). Al superarlo, la API rechaza tus solicitudes durante un máximo de 30 minutos. Algunos endpoints también responden RATE_LIMITED por sus propios límites, y una dirección IP que sigue enviando claves de API que no pertenecen a ninguna cuenta queda bloqueada durante un breve periodo.
  • KEEP_CALM: el límite propio de un endpoint, como un reinicio cada pocos segundos. Espera un momento y vuelve a intentarlo. El límite de cada endpoint está en su página.

Autenticación y permisos

Validación de la solicitud

Cuotas y límites de conexión

Aplicaciones

Upload y commit

Comprobaciones del zip y de la configuración

Cuando subes una aplicación, el servidor que la ejecutará comprueba el zip y su archivo de configuración (squarecloud.app o squarecloud.config). Una comprobación fallida responde 400 con uno de estos códigos, y no se hace deploy de nada. Corrige el zip y vuelve a subirlo. Un commit no lee el archivo de configuración: de esta lista, solo puede fallar con FAILED_EXTRACT o CONTAINER_INSUFFICIENT_DISK_SPACE.

Variables de entorno

Archivos

Deploys y GitHub

Un deploy de Git fallido no es un error HTTP: aparece en el historial de deploys como un evento con state: "error" y un code como DEPLOY_FAILED.

Red y dominios

Snapshots

Bases de datos

Workspaces

Plataforma

Los códigos AI_* (AI_DAILY_LIMIT_REACHED, AI_NO_PLAN_LIMIT_REACHED, AI_MAX_CONCURRENT_STREAMS, AI_UNAVAILABLE) pertenecen al asistente de IA del panel, que necesita una sesión del panel. Una clave de API nunca los recibe.

Relacionado