调用 API 前必须先获取 API Key

所有 API 请求均需通过 X-API-Key 请求头进行身份认证。没有有效的 API Key，任何端点都无法调用。

概述

ImgRoute API 使用统一的错误响应格式，所有错误都会返回结构化的 JSON 响应，便于客户端解析和处理。

错误响应格式

{
  "success": false,
  "error": "错误描述",
  "code": "ERROR_CODE"
}

HTTP 状态码

状态码含义典型场景
400请求参数错误缺少必填参数、参数格式错误、尺寸不匹配
401认证失败未提供 API Key、API Key 无效
403权限不足套餐不支持此功能、存储已达上限
404资源不存在图片或相册 ID 不存在
429请求过于频繁QPS 超限或日配额用尽
500服务器内部错误系统异常，请稍后重试
503服务暂不可用IO 节点维护或过载

完整错误码列表

参数错误 (400)

错误码说明
MISSING_FILE_SIZE缺少 file_size 参数
MISSING_FILE_NAME缺少 file_name 参数
MISSING_MIME_TYPE缺少 mime_type 参数
MISSING_WIDTH缺少 width 参数
MISSING_HEIGHT缺少 height 参数
INVALID_WIDTHwidth 必须为正整数
INVALID_HEIGHTheight 必须为正整数
INVALID_DIMENSIONwidth/height 非法或不为正整数
DIMENSION_MISMATCH实际图片尺寸与声明不一致
INVALID_FILE_SIZEfile_size 必须为正整数
FILE_TOO_LARGE单文件超出套餐限制
MISSING_NAME相册名称为空
INVALID_PARAMS参数非法或冲突
MISSING_PARAMS缺少必填参数
VALIDATION_ERROR参数校验失败

认证错误 (401)

错误码说明
MISSING_API_KEY未提供 API Key
INVALID_API_KEYAPI Key 无效

权限错误 (403)

错误码说明
PLAN_NOT_SUPPORTED当前套餐不支持此接口
FORBIDDEN无权操作此资源
STORAGE_LIMIT_REACHED存储总量已达上限

限流错误 (429)

错误码说明
DAILY_LIMIT_REACHED超过今日上传限制
RATE_LIMITED触发 QPS 限制

错误处理代码示例

import requests

def upload_image(file_path):
    try:
        presign_resp = requests.post(
            "https://imgroute.com/api/v1/upload",
            headers={"X-API-Key": API_KEY},
            json={...}
        )

        if not presign_resp.ok:
            error = presign_resp.json()
            print(f"预签名失败: {error['code']} - {error['error']}")
            return None

        upload_url = presign_resp.json()["data"]["upload_url"]

        with open(file_path, "rb") as f:
            upload_resp = requests.post(upload_url, files={"file": f})

        if not upload_resp.ok:
            error = upload_resp.json()
            print(f"上传失败: {error['code']} - {error['error']}")
            return None

        return upload_resp.json().get("cdn_url")

    except requests.exceptions.RequestException as e:
        print(f"网络错误: {e}")
        return None

重试策略建议

  • 4xx 客户端错误：不要重试，修复请求后再试
  • 429 限流：根据 Retry-After 头等待后重试
  • 5xx 服务器错误：使用指数退避重试
  • 网络错误：检查网络连接，使用指数退避重试