Skip to main content
Ogni richiesta non riuscita all’API di Square Cloud risponde con uno stato HTTP e un body JSON che contiene un code leggibile dalle macchine. Questa pagina elenca tutti i codici, raggruppati per area. Anche la pagina di ogni endpoint elenca i codici che quell’endpoint restituisce più spesso.
Blob Storage ha un proprio elenco di codici, e l’AI Gateway risponde nel formato di errore di OpenAI con codici in minuscolo. Nessuno dei due è trattato qui.

Formato degli errori

L’elenco dei codici cresce nel tempo. Tratta un codice che non conosci come un errore generico dello stato HTTP con cui è arrivato: correggi la richiesta su un 4xx, attendi su un 429 e riprova più tardi su un 5xx.

Nuovi tentativi

L’API non invia l’header Retry-After, quindi la decisione spetta a te. Una strategia sicura: 202 SNAPSHOT_PROCESSING mantiene il formato di errore per compatibilità, ma non è un errore: lo snapshot è ancora in fase di generazione e comparirà da solo nell’elenco. Non richiederlo di nuovo.

Limiti di frequenza

Due codici rispondono 429, con significati diversi:
  • RATE_LIMITED: il budget di richieste del tuo account o della tua chiave API, conteggiato ogni 60 secondi e stabilito dal tuo piano (vedi i valori per piano). Una volta superato, l’API rifiuta le tue richieste per un massimo di 30 minuti. Alcuni endpoint rispondono RATE_LIMITED anche per i propri limiti, e un indirizzo IP che continua a inviare chiavi API che non appartengono a nessun account viene bloccato per un breve periodo.
  • KEEP_CALM: il limite proprio di un singolo endpoint, ad esempio un riavvio ogni pochi secondi. Attendi un momento e riprova. Il limite di ogni endpoint è indicato nella sua pagina.

Autenticazione e permessi

Validazione della richiesta

Quote e limiti di connessione

Applicazioni

Upload e commit

Controlli dello zip e della configurazione

Quando carichi un’applicazione, il server che la eseguirà controlla lo zip e il suo file di configurazione (squarecloud.app o squarecloud.config). Un controllo non superato risponde 400 con uno di questi codici, e non viene distribuito nulla. Correggi lo zip e caricalo di nuovo. Un commit non legge il file di configurazione: di questo elenco può fallire solo con FAILED_EXTRACT o CONTAINER_INSUFFICIENT_DISK_SPACE.

Variabili d’ambiente

File

Deploy e GitHub

Un deploy Git non riuscito non è un errore HTTP: compare nella cronologia dei deploy come evento con state: "error" e un code come DEPLOY_FAILED.

Rete e domini

Snapshot

Database

Workspace

Piattaforma

I codici AI_* (AI_DAILY_LIMIT_REACHED, AI_NO_PLAN_LIMIT_REACHED, AI_MAX_CONCURRENT_STREAMS, AI_UNAVAILABLE) appartengono all’assistente AI della dashboard, che richiede una sessione della dashboard. Una chiave API non li riceve mai.

Vedi anche