Quando algo dá errado.
Os erros retornam como um envelope JSON com um type estável, uma mensagem legível e um request_id que você pode nos enviar ao relatar um problema.
{"type": "error", "error": {
"type": "authentication_error",
"message": "Invalid or revoked API key.",
"request_id": "063f8b83-eee2-4383-a5cf-11e4bcd29d7c"
}}| HTTP | Significado | O que fazer |
|---|---|---|
| 400 | Corpo malformado (campo ausente ou de tipo errado) | A mensagem indica o campo exato - corrija e tente novamente. |
| 401 | Chave de API inválida ou revogada | Verifique a chave; emita uma nova no console. |
| 402 | Saldo esgotado, nenhum cartão cadastrado, ou limite do nível atingido | Adicione créditos ou cadastre um cartão no console. A resposta traz balance_cents e floor_cents, então você consegue saber qual dos dois barrou a chamada. |
| 404 | Memória, store ou imagem inexistente | Verifique o id. get_image também responde 404 quando a memória existe mas não carrega nenhuma imagem. |
| 409 | Esse nome já está em uso | Os nomes de store e de workspace são únicos dentro de uma conta - escolha outro. |
| 413 | Corpo da requisição acima de 10MB | O Base64 fica cerca de 33% maior que o arquivo que codifica, então redimensione a imagem antes de codificá-la. |
| 429 | Limite de requisições excedido | O SDK já tenta novamente por você, com recuo e jitter, respeitando o Retry-After. Receber um deles significa que as tentativas se esgotaram - reduza a sua concorrência em vez de envolver tudo em um laço próprio. |
| 501 | O motor deste modelo não implementa esse endpoint | Imagens e histórico de revisões exigem um motor mais recente. GET /api/v1/models lista quais modelos atendem o quê. |
| 5xx | Problema no servidor | Tente novamente com recuo, mas não às cegas. O SDK não repete automaticamente um 5xx aqui, porque toda chamada desta API é um POST e o servidor pode já ter armazenado a sua solicitação. Reenvie com uma chave de idempotência para que uma repetição não possa gravar duas vezes, e inclua o request_id se entrar em contato conosco. |
Todo erro é um WosError, e cada status também tem uma classe própria - BadRequestError, AuthenticationError, PaymentRequiredError, NotFoundError, ConflictError, RateLimitError, ServerError, APIConnectionError. Capture aquela que você pretende tratar em 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
Alguns erros nunca chegam até nós. A chave de API, o id do store, a chave de idempotência e a imagem são todos verificados antes de a requisição sair, e nesses casos o que é levantado é ValueError ou TypeError - não WosError. Um except WosError sozinho não vai capturá-los.
Os limites de requisições são por conta, compartilhados entre todas as suas chaves, e escalam com o seu nível - veja Níveis de uso. O uso da sua conta é exibido no console.