标准错误码与 JSON 信封规范
SmallPict API 的权威错误码对照表、统一 JSON 响应格式与 HTTP 状态码映射。
SmallPict 所有异常状态均统一返回遵循规范的 JSON 信封，附带强类型机器可读错误码。
统一错误 JSON 数据结构
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" } }}权威错误码对照表
| HTTP 状态码 | 业务错误代码 (Enum) | 对应 SDK 异常类 | 错误场景详细说明 |
|---|---|---|---|
| 400 | VALIDATION_FAILED | ValidationError | 请求载荷未通过校验或缺少必填参数 |
| 400 | FILE_TOO_LARGE | FileTooLargeError | 单张图片上传大小超出了当前套餐上限 |
| 400 | UNSUPPORTED_FORMAT | UnsupportedFormatError | 上传的文件不是受支持的图片格式 |
| 401 | UNAUTHORIZED | AuthenticationError | 缺少或非法的 API Key、时间戳或签名 |
| 401 | ERR_TIMESTAMP_DRIFT | AuthenticationError | 客户端时间戳超出允许的 ±300 秒漂移范围 |
| 402 | QUOTA_EXCEEDED | QuotaExceededError | 当月图片处理配额已耗尽 |
| 402 | OVERAGE_EXCEEDED | QuotaExceededError | 超出套餐允许的超额缓冲限额 |
| 403 | FORBIDDEN | PermissionDeniedError | 密钥已被吊销或账户处于冻结状态 |
| 403 | KEY_SCOPE_MISMATCH | ScopeMismatchError | 密钥权限范围与调用的接口不匹配 |
| 404 | NOT_FOUND | NotFoundError | 目标任务 ID (job_id) 或资源不存在 |
| 429 | RATE_LIMIT_EXCEEDED | RateLimitError | 短时间内请求频次过高，请遵循 Retry-After |
| 500 | INTERNAL_ERROR | ServerError | 服务端遇到未捕获异常，已记录审计日志 |
| 502 | CDN_UPSTREAM_ERROR | CdnError | SmallPict 边缘 CDN 刷新或源站同步异常 |
SDK 容错机制
SmallPict 官方 SDK 会自动将这些 JSON 错误解包为当前语言的原生强类型异常，并在遇到瞬时性的 429 和 5xx 错误时自动启用内置抖动退避重试。