Mã lỗi chuẩn & Cấu trúc JSON

Bảng đối chiếu mã lỗi chính thức, cấu trúc JSON trả về và ánh xạ mã trạng thái HTTP của SmallPict API.

Tất cả các phản hồi lỗi từ SmallPict API đều được đóng gói theo một cấu trúc JSON tiêu chuẩn với các mã lỗi định kiểu rõ ràng, thuận tiện cho việc xử lý tự động bằng máy.

Cấu trúc JSON phản hồi lỗi tiêu chuẩn

JSON

{  "error": {    "code": "QUOTA_EXCEEDED",    "message": "Monthly image processing quota limit reached for your plan.",    "details": {      "current_bytes": 10737418240,      "quota_bytes": 10737418240,      "reset_at": "2026-09-01T00:00:00Z"    }  }}

Bảng đối chiếu mã lỗi toàn diện

Mã HTTP	Mã lỗi Enum	Lớp ngoại lệ SDK	Mô tả chi tiết nguyên nhân lỗi
400	`VALIDATION_FAILED`	`ValidationError`	Dữ liệu gửi lên không đúng định dạng hoặc thiếu trường bắt buộc
400	`FILE_TOO_LARGE`	`FileTooLargeError`	Kích thước tệp tải lên vượt quá giới hạn tối đa của gói hiện tại
400	`UNSUPPORTED_FORMAT`	`UnsupportedFormatError`	Định dạng tệp cung cấp không được hệ thống hỗ trợ
401	`UNAUTHORIZED`	`AuthenticationError`	Thiếu hoặc không hợp lệ khóa API, dấu thời gian hoặc chữ ký HMAC
401	`ERR_TIMESTAMP_DRIFT`	`AuthenticationError`	Thời gian của máy khách vượt quá độ lệch cho phép (±300 giây)
402	`QUOTA_EXCEEDED`	`QuotaExceededError`	Đã dùng hết hạn ngạch xử lý hình ảnh của tháng hiện tại
402	`OVERAGE_EXCEEDED`	`QuotaExceededError`	Vượt quá giới hạn dung lượng bộ đệm dự phòng cho phép
403	`FORBIDDEN`	`PermissionDeniedError`	Khóa API đã bị thu hồi hoặc tài khoản đang bị tạm khóa
403	`KEY_SCOPE_MISMATCH`	`ScopeMismatchError`	Phạm vi quyền hạn của khóa API không khớp với điểm cuối được gọi
404	`NOT_FOUND`	`NotFoundError`	Mã công việc (`job_id`) hoặc tài nguyên được yêu cầu không tồn tại
429	`RATE_LIMIT_EXCEEDED`	`RateLimitError`	Gửi quá nhiều yêu cầu trong thời gian ngắn (vui lòng tuân thủ `Retry-After`)
500	`INTERNAL_ERROR`	`ServerError`	Đã xảy ra lỗi không mong muốn trên máy chủ (đã ghi nhận nhật ký an toàn)
502	`CDN_UPSTREAM_ERROR`	`CdnError`	Lỗi xảy ra khi xóa bộ nhớ đệm hoặc đồng bộ dữ liệu tới SmallPict Edge CDN

Khả năng phục hồi và xử lý lỗi của SDK

Các SDK chính thức của SmallPict tự động đóng gói các lỗi JSON này thành các ngoại lệ định kiểu theo từng ngôn ngữ và tự động kích hoạt cơ chế thử lại có độ trễ ngẫu nhiên khi gặp các lỗi tạm thời 429 và 5xx.