문제가 생겼을 때.
에러는 안정적인 type, 사람이 읽는 메시지, 그리고 문의 시 함께 보낼 수 있는 request_id가 담긴 JSON 봉투로 옵니다.
실제 응답 - 잘못된 키 (HTTP 401)
{"type": "error", "error": {
"type": "authentication_error",
"message": "Invalid or revoked API key.",
"request_id": "063f8b83-eee2-4383-a5cf-11e4bcd29d7c"
}}| HTTP | 의미 | 대처 |
|---|---|---|
| 400 | 잘못된 바디 (필드 누락/타입 오류) | 메시지에 정확한 필드가 나옵니다 - 고치고 재시도. |
| 401 | 잘못됐거나 폐기된 API 키 | 키 확인, 콘솔에서 재발급. |
| 402 | 잔액 부족, 카드 미등록, 또는 티어 상한 | 콘솔에서 충전하거나 카드를 등록하세요. 응답에 balance_cents 와 floor_cents 가 들어 있어 무엇에 막혔는지 구분됩니다. |
| 404 | 없는 기억·저장소·이미지 | id 를 확인하세요. get_image 는 기억이 있어도 이미지이 없으면 404 입니다. |
| 409 | 이미 쓰고 있는 이름 | 저장소와 워크스페이스 이름은 계정 안에서 고유합니다 - 다른 이름을 쓰세요. |
| 413 | 바디가 10MB 초과 | base64 는 원본 파일보다 약 33% 큽니다. 이미지을 줄인 뒤 인코딩하세요. |
| 429 | 요청 한도 초과 | SDK 가 이미 백오프와 지터로 재시도하며 Retry-After 를 지킵니다. 이 에러를 받았다는 것은 재시도가 소진됐다는 뜻이니, 직접 루프를 감지 말고 동시 요청을 줄이세요. |
| 501 | 이 모델의 엔진이 그 엔드포인트를 구현하지 않음 | 이미지과 수정 이력은 더 새 엔진이 필요합니다. GET /api/v1/models 에서 어떤 모델이 무엇을 지원하는지 볼 수 있습니다. |
| 5xx | 서버 측 문제 | 백오프 후 재시도하되 무작정 하지는 마세요. 이 API 는 모든 호출이 POST 라 서버가 이미 저장했을 수 있어서, SDK 는 5xx 를 자동 재시도하지 않습니다. 다시 보낼 때는 멱등키를 붙여 중복 저장을 막고, 문의 시 request_id 를 함께 보내주세요. |
모든 에러는 WosError 이고, 상태마다 전용 클래스도 있습니다 - BadRequestError, AuthenticationError, PaymentRequiredError, NotFoundError, ConflictError, RateLimitError, ServerError, APIConnectionError. 숫자를 비교하지 말고 다루려는 것을 직접 잡으세요.
# 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
어떤 실수는 저희에게 닿지도 않습니다. API 키, 저장소 id, 멱등키, 이미지은 요청을 보내기 전에 검사하며, 그때는 WosError 가 아니라 ValueError 나 TypeError 가 납니다. except WosError 만으로는 안 잡힙니다.
키 안전. 키는 생성 시 한 번만 표시되고 서버에는 해시로만 저장됩니다. 환경변수로 보관하고, 유출 시 콘솔에서 폐기하세요 - 폐기는 즉시 적용됩니다.
요청 한도는 계정 단위로 모든 키가 공유하며, 티어에 따라 올라갑니다 - 사용량 티어 참고. 계정 사용량은 콘솔에 표시됩니다.