Quand quelque chose tourne mal.
Les erreurs reviennent sous forme d'enveloppe JSON avec un type stable, un message lisible et un request_id que vous pouvez nous transmettre pour signaler un problème.
{"type": "error", "error": {
"type": "authentication_error",
"message": "Invalid or revoked API key.",
"request_id": "063f8b83-eee2-4383-a5cf-11e4bcd29d7c"
}}| HTTP | Signification | Que faire |
|---|---|---|
| 400 | Corps malformé (champ manquant ou de mauvais type) | Le message nomme le champ exact - corrigez et réessayez. |
| 401 | Clé API invalide ou révoquée | Vérifiez la clé ; émettez-en une nouvelle dans la console. |
| 402 | Solde épuisé, aucune carte enregistrée, ou plafond de palier atteint | Rechargez votre solde ou enregistrez une carte dans la console. La réponse contient balance_cents et floor_cents, ce qui vous indique lequel des deux vous a arrêté. |
| 404 | Souvenir, store ou image introuvable | Vérifiez l'id. get_image répond également 404 lorsque le souvenir existe mais ne porte aucune image. |
| 409 | Ce nom est déjà pris | Les noms de store et de workspace sont uniques au sein d'un compte - choisissez-en un autre. |
| 413 | Corps de requête au-delà de 10MB | Le Base64 pèse environ 33% de plus que le fichier qu'il encode, redimensionnez donc l'image avant de l'encoder. |
| 429 | Limite de débit atteinte | Le SDK réessaie déjà pour vous, avec backoff et jitter, en respectant Retry-After. En recevoir une signifie que les tentatives sont épuisées - réduisez le nombre d'appels simultanés plutôt que d'enrouler votre propre boucle autour. |
| 501 | Le moteur de ce modèle n'implémente pas cet endpoint | Les images et l'historique des révisions demandent un moteur plus récent. GET /api/v1/models indique quels modèles servent quoi. |
| 5xx | Problème côté serveur | Réessayez avec backoff, mais pas aveuglément. Le SDK ne réessaie pas automatiquement un 5xx ici, car chaque appel de cette API est un POST et le serveur a peut-être déjà enregistré votre requête. Renvoyez-la avec une clé d'idempotence pour qu'une répétition ne puisse pas écrire deux fois, et joignez le request_id si vous nous contactez. |
Chaque erreur est un WosError, et chaque statut possède en plus sa propre classe - BadRequestError, AuthenticationError, PaymentRequiredError, NotFoundError, ConflictError, RateLimitError, ServerError, APIConnectionError. Attrapez celle que vous voulez traiter au lieu de comparer des numéros.
# SDK error handling (Python) from wontopos import Client, WosError, RateLimitError, PaymentRequiredError try: mem.search("...", user_id="alice") except PaymentRequiredError: ... # 402 - top up except RateLimitError: ... # 429 - the SDK already retried; slow down except WosError as e: ... # e.status, e.message, e.request_id except (ValueError, TypeError): ... # never left the client
Certaines erreurs ne nous parviennent jamais. La clé API, l'id du store, la clé d'idempotence et l'image sont toutes vérifiées avant l'envoi de la requête, et celles-là lèvent ValueError ou TypeError - pas WosError. Un except WosError seul ne les attrapera pas.
Les limites de débit sont par compte, partagées entre toutes vos clés, et augmentent avec votre palier - voir Paliers d'utilisation. L'usage de votre compte est visible dans la console.