*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 lectx 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 :
*APIError :
Realtime.Nextrenvoie lectx.Err()brut lorsque sonctxse termine, etio.EOFlorsque 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 queencoding/jsonne peut pas encoder, et une erreur duio.Writerpassé à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 401ACCESS_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_LIMITEDpeut être un blocage d’environ 30 minutes, etKEEP_CALMn’est pas réessayé non plus ; - les autres 5xx ;
- les erreurs d’IA.
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 deAccount.Snapshots. - 429
KEEP_CALM: trop d’appels vers une même route en peu de temps.
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.

