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. Les extraits plus courts ci-dessous s’exécutent dans le programme présenté dans Exécuter les exemples : collez-en un à la fois dans main et lancez goimports.

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. 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. La liste des codes de l’API s’allonge. Traitez un code inconnu d’après son statut HTTP :

Codes d’erreur de l’API

Tous les autres codes viennent de l’API. La référence des erreurs de l’API liste chacun d’eux avec son statut HTTP, sa signification et sa solution, et chaque page du SDK liste les codes que ses méthodes renvoient le plus souvent. N’importe quel appel peut aussi répondre 401 ACCESS_DENIED (une clé invalide), 403 MISSING_SCOPE ou RESOURCE_NOT_ALLOWED (les limites de la clé), 429 (voir Limites de débit) ou 503 DATABASE_UNAVAILABLE. 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 : le compte ou la clé API a dépassé son budget de requêtes et est bloqué pendant environ 30 minutes, ou une IP qui envoie sans cesse des clés invalides est bloquée pendant une courte période. 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.

Prochaines étapes

Référence des erreurs de l'API

Chaque code d’erreur, avec sa signification et sa solution.

Limitations et restrictions

Les limites de requêtes de chaque plan.