Cuando algo sale mal.
Los errores vuelven como un sobre JSON con un type estable, un mensaje legible y un request_id que puedes enviarnos al reportar un problema.
{"type": "error", "error": {
"type": "authentication_error",
"message": "Invalid or revoked API key.",
"request_id": "063f8b83-eee2-4383-a5cf-11e4bcd29d7c"
}}| HTTP | Significado | Qué hacer |
|---|---|---|
| 400 | Cuerpo mal formado (campo faltante o de tipo incorrecto) | El mensaje indica el campo exacto - corrige y reintenta. |
| 401 | Clave de API inválida o revocada | Verifica la clave; emite una nueva en la consola. |
| 402 | Saldo agotado, sin tarjeta registrada, o tope de nivel alcanzado | Recarga saldo o añade una tarjeta en la consola. La respuesta incluye balance_cents y floor_cents, así puedes saber cuál de los dos te detuvo. |
| 404 | No existe esa memoria, store o imagen | Verifica el id. get_image también responde 404 cuando la memoria existe pero no lleva ninguna imagen. |
| 409 | Ese nombre ya está en uso | Los nombres de store y de workspace son únicos dentro de una cuenta - elige otro. |
| 413 | Cuerpo de la solicitud por encima de 10MB | Base64 ocupa alrededor de un 33% más que el archivo que codifica, así que redimensiona la imagen antes de codificarla. |
| 429 | Límite de velocidad excedido | El SDK ya los reintenta por ti, con espera exponencial y jitter, respetando Retry-After. Recibir uno significa que los reintentos se agotaron - baja tu concurrencia en lugar de envolverlo en un bucle propio. |
| 501 | El motor de este modelo no implementa ese endpoint | Las imágenes y el historial de revisiones necesitan un motor más reciente. GET /api/v1/models lista qué modelos sirven qué. |
| 5xx | Problema del lado del servidor | Reintenta con espera exponencial, pero no a ciegas. El SDK no reintenta automáticamente un 5xx aquí, porque cada llamada de esta API es un POST y el servidor puede haber guardado ya tu solicitud. Reenvíala con una clave de idempotencia para que una repetición no pueda escribir dos veces, e incluye el request_id si nos contactas. |
Todo error es un WosError, y cada estado tiene además su propia clase - BadRequestError, AuthenticationError, PaymentRequiredError, NotFoundError, ConflictError, RateLimitError, ServerError, APIConnectionError. Captura la que quieras manejar en vez de comparar números.
# 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
Algunos errores nunca llegan hasta nosotros. La clave de API, el id del store, la clave de idempotencia y la imagen se comprueban antes de que salga la solicitud, y ahí se lanza ValueError o TypeError - no WosError. Un except WosError por sí solo no los atrapará.
Los límites de velocidad son por cuenta, se comparten entre todas tus claves y escalan con tu nivel - consulta Niveles de uso. El uso de tu cuenta se muestra en la consola.