SDK Python : erreurs et nouvelles tentatives

Chaque échec de l’API ou du réseau lève une seule exception : SquareCloudAPIError. Les exemples utilisent le client présenté dans Créer le client. app_id est l’identifiant de l’une de vos applications : client.account.me() les liste.

from squarecloud import SquareCloudAPIError

try:
    client.apps.start(app_id)
except SquareCloudAPIError as error:
    print(error.status, error.code, error.message)
    print(error.method, error.path)  # "POST" "/v2/apps/<id>/start"
    print(error)  # POST /v2/apps/<id>/start: HTTP 404 APP_NOT_FOUND

`SquareCloudAPIError`

SquareCloudAPIError est une sous-classe d’Exception.

Attribut	Type	Description
`status`	`int`	Statut HTTP. `0` lorsqu’aucune réponse n’est arrivée (erreur réseau, timeout, vérification locale)
`code`	`str`	Le code d’erreur de l’API, par ex. `APP_NOT_FOUND`, ou l’un des codes du SDK
`message`	`str`	L’explication du serveur. `''` lorsque le serveur n’a envoyé qu’un code
`method`	`str`	Méthode HTTP de l’appel échoué
`path`	`str`	Chemin de l’URL de l’appel échoué, sans la chaîne de requête
`cause`	`BaseException \| None`	L’exception d’origine, pour `NETWORK_ERROR`, `TIMEOUT` et un JSON invalide (la même que `__cause__`)

str(error) vaut <METHOD> <path>: HTTP <status> <CODE>: <message>, sans HTTP <status> lorsque le statut est 0 et sans : <message> lorsque le message est vide. Deux échecs ne sont pas encapsulés :

Une clé API vide ou composée uniquement d’espaces lève une ValueError dans le constructeur du client.
Les problèmes de fichiers locaux lèvent une OSError : un chemin d’envoi qui ne peut pas être ouvert, un fichier qui devient illisible pendant l’envoi, ou une destination de download_snapshot impossible à écrire.

Codes du SDK

Statut	Code	Quand
0	`NETWORK_ERROR`	Aucune réponse (DNS, connexion réinitialisée, corps tronqué). L’exception d’origine se trouve dans `cause`
0	`TIMEOUT`	Une opération de socket a dépassé le timeout
0	`FILE_TOO_LARGE`	Vérification locale : un envoi de plus de 100 Mo ou un `files.write` de plus de 10 Mo. Rien n’a été envoyé
0	`INVALID_ID`	Vérification locale : un identifiant vide, `.` ou `..`. Rien n’a été envoyé
tous	`UNKNOWN_ERROR`	Une réponse sans code (comme une page d’erreur de proxy), avec le vrai `status` et le message du serveur, ou `HTTP <status>` s’il n’y en a pas. Un corps 2xx qui n’est pas du JSON a le message `Invalid JSON in HTTP <status> response`

Les codes sont des chaînes

code est une simple str : le SDK n’a pas d’enum de codes. La docstring de SquareCloudAPIError liste tous les codes connus de l’API. RATE_LIMIT et RATE_LIMIT_EXCEEDED y figurent toujours, marqués comme dépréciés : l’API répond désormais RATE_LIMITED pour les deux. La liste des codes de l’API s’allonge. Traitez un code inconnu d’après son statut HTTP :

def start(app_id: str):
    try:
        client.apps.start(app_id)
    except SquareCloudAPIError as error:
        match error.code:
            case "APP_NOT_FOUND":
                return None
            case "CONTAINER_ALREADY_STARTED":
                return  # fine
            case _:
                if error.status == 429:
                    return retry_later()
                if error.status >= 500:
                    return report_outage(error)
                raise

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, …). Voir IA.

Nouvelles tentatives

Le SDK ne réessaie que ce qui peut être répété sans risque, jusqu’à max_retries fois (par défaut 2, soit jusqu’à 3 tentatives) :

Réessayé	Méthodes
`NETWORK_ERROR`	`GET` uniquement
503 `UPLOAD_BUSY`	Toute méthode
503 `ANALYTICS_BUSY`	Toute méthode
503 `DATABASE_UNAVAILABLE`	`GET` uniquement

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. 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 max_retries=0 pour désactiver les nouvelles tentatives.

Timeouts

timeout (30 s) s’applique par opération de socket (la connexion et chaque lecture ou écriture), et non à toute la requête. Voir Timeouts pour les appels avec un plancher de 120 s et les appels sans timeout. Un timeout lève TIMEOUT avec le statut 0 et n’est jamais réessayé.

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.

CLI

VS Code

SDKs

SDK Python : erreurs et nouvelles tentatives

`SquareCloudAPIError`

Codes du SDK

Les codes sont des chaînes

Codes d’erreur de l’API

Nouvelles tentatives

Timeouts

Limites de débit

Prochaines étapes

Référence des erreurs de l'API

Limitations et restrictions

​SquareCloudAPIError

​Codes du SDK

​Les codes sont des chaînes

​Codes d’erreur de l’API

​Nouvelles tentatives

​Timeouts

​Limites de débit

​Prochaines étapes

Référence des erreurs de l'API

Limitations et restrictions

`SquareCloudAPIError`

Codes du SDK

Les codes sont des chaînes

Codes d’erreur de l’API

Nouvelles tentatives

Timeouts

Limites de débit

Prochaines étapes