Skip to main content
Chaque échec de l’API, du réseau ou local est d’un seul type : *squarecloud.APIError. Inspectez-le avec errors.As.

APIError

Unwrap() renvoie la cause (l’erreur de transport, de décodage ou de contexte) pour NETWORK_ERROR, TIMEOUT et un JSON invalide, sinon nil. Error() produit squarecloud: <METHOD> <path>: HTTP <status> <CODE>: <message>, sans HTTP <status> lorsque le statut vaut 0 et sans : <message> lorsqu’il est vide. Basez-vous sur les champs, pas sur ce texte.

Contextes annulés et expirés

Un appel dont le ctx est annulé renvoie une *APIError avec NETWORK_ERROR, et un appel dont l’échéance est dépassée renvoie TIMEOUT, tous deux avec le statut 0. Ils encapsulent l’erreur du contexte :
Quelques échecs ne sont pas des *APIError :
  • Realtime.Next renvoie le ctx.Err() brut lorsque son ctx se termine, et io.EOF lorsque le flux se termine normalement.
  • Les problèmes du côté de l’appelant sont des erreurs ordinaires : un reader d’envoi nil, une URL de snapshot ou une URL de base qui ne peut pas être analysée, une entrée que encoding/json ne peut pas encoder, et une erreur du io.Writer passé à DownloadSnapshot.

Codes du SDK

Constantes Code*

Code est une simple string. Le paquet contient une constante par code public de l’API, nommée d’après lui dans le style Go (CodeAppNotFound pour APP_NOT_FOUND, CodeInvalidID, CodeDNSFailed, …), plus les codes propres au SDK ci-dessus. La liste des codes de l’API s’allonge. Traitez un code inconnu d’après son statut HTTP :

Erreurs de n’importe quel appel

Codes de l’API par groupe

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) et CodeRateLimitExceeded (RATE_LIMIT_EXCEEDED) sont toujours exportées, marquées comme dépréciées : l’API répond désormais RATE_LIMITED (CodeRateLimited) pour les deux.
Les erreurs de AI.Chat utilisent plutôt les codes OpenAI en minuscules (access_denied, rate_limit_exceeded, server_overloaded, …), que Code reprend tels quels. Voir IA.

Nouvelles tentatives

Le SDK ne réessaie que ce qui peut être répété sans risque, jusqu’à WithMaxRetries fois (par défaut 2, soit jusqu’à 3 tentatives) : Il ne réessaie jamais :
  • TIMEOUT ;
  • aucun 429 : RATE_LIMITED peut être un blocage d’environ 30 minutes, et KEEP_CALM n’est pas réessayé non plus ;
  • les autres 5xx ;
  • les erreurs d’IA.
503 DATABASE_UNAVAILABLE peut arriver alors qu’une mutation a déjà été appliquée : le SDK ne la réessaie donc pas en dehors de GET. Réessayez vous-même vos mutations idempotentes si nécessaire. Un envoi n’est réessayé que si son corps peut être rejoué : un io.ReaderAt de taille connue, comme un *os.File (voir Commit et envoi). L’attente avant la nouvelle tentative n (à partir de 0) est min(8 s, 500 ms · 2^n) · U(0.5, 1) : un backoff exponentiel avec un jitter de 50 % à 100 %. Définissez WithMaxRetries(0) pour désactiver les nouvelles tentatives.

Timeouts

WithTimeout (30 s) ne s’applique que lorsque ctx n’a pas d’échéance, et une seule échéance couvre tout l’appel, nouvelles tentatives et attentes de backoff comprises. Voir Timeouts pour les appels avec un plancher de 2 minutes et les appels sans échéance par défaut. Une échéance dépassée renvoie TIMEOUT avec le statut 0, n’est jamais réessayée et encapsule context.DeadlineExceeded.

Limites de débit

Chaque compte dispose d’une limite de requêtes par 60 secondes, fixée par son plan (valeurs), et certaines routes ont la leur :
  • 429 RATE_LIMITED : un blocage du compte, de la clé API ou de l’IP, qui peut durer environ 30 minutes. C’est aussi la limite des endpoints réseau et de Account.Snapshots.
  • 429 KEEP_CALM : trop d’appels vers une même route en peu de temps.
Le SDK ne réessaie jamais un 429. Ralentissez, et attendez avant de réessayer.