错误

Scavio API使用标准HTTP状态码并返回结构化错误响应，帮助您快速调试问题。

错误响应格式

JSON

{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable error description"
  }
}

状态码

状态	代码	描述
400	`bad_request`	无效的请求体或缺少必需参数
401	`unauthorized`	缺少或无效的API密钥
403	`forbidden`	API密钥没有执行此操作的权限
402	`insufficient_credits`	积分不足。请充值或升级计划。
429	`rate_limit_exceeded`	请求过多。等待后重试。
500	`internal_error`	服务器错误。短暂延迟后重试。

常见错误

缺少query参数

400 Bad Request

{
  "error": {
    "code": "bad_request",
    "message": "The 'query' field is required"
  }
}

无效的search_type

400 Bad Request

{
  "error": {
    "code": "bad_request",
    "message": "Invalid search_type. Must be one of: classic, news, maps, images, lens"
  }
}

无效的API密钥

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

积分不足

402 Payment Required

{
  "error": {
    "code": "insufficient_credits",
    "message": "No credits remaining. Please upgrade your plan or purchase additional credits."
  }
}

速率限制

429 Too Many Requests

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 30 seconds."
  }
}

最佳实践

在解析响应体之前始终检查HTTP状态码
使用 error.code 字段进行程序化错误处理
使用 error.message 字段进行日志记录和调试
为429和500错误实现带指数退避的重试逻辑
不要重试400或401错误 -- 先修复请求

状态码

状态

代码

描述

400

bad_request

无效的请求体或缺少必需参数

401

unauthorized

缺少或无效的API密钥

403

forbidden

API密钥没有执行此操作的权限

402

insufficient_credits

积分不足。请充值或升级计划。

429

rate_limit_exceeded

请求过多。等待后重试。

500

internal_error

服务器错误。短暂延迟后重试。

常见错误

缺少query参数

400 Bad Request

{
  "error": {
    "code": "bad_request",
    "message": "The 'query' field is required"
  }
}

无效的search_type

400 Bad Request

{
  "error": {
    "code": "bad_request",
    "message": "Invalid search_type. Must be one of: classic, news, maps, images, lens"
  }
}

无效的API密钥

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

积分不足

402 Payment Required

{
  "error": {
    "code": "insufficient_credits",
    "message": "No credits remaining. Please upgrade your plan or purchase additional credits."
  }
}

速率限制

429 Too Many Requests

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 30 seconds."
  }
}