错误处理

所有错误返回统一结构,HTTP 状态码 + JSON:

{ "error": { "code": "rate_limited", "message": "请求过于频繁，请稍后再试" } }

状态码	code	含义
400	bad_request	参数或请求体不合法(如畸形 JSON、缺必填项)
400	country_not_supported	/v1/image-search 的 country 仅支持 US、CN
401	invalid_key	缺少或无效的 API Key
402	—	API 点月度配额不足,需升级 / 续费 API 套餐
403	forbidden_entitlement	当前档位无权使用该能力
405	method_not_allowed	HTTP 方法错误(如对 POST 端点用了 GET)
429	rate_limited	触发限流(高频突发,建议降速重试)

计费保护

参数校验(含坏图、country 校验)在扣费之前完成 —— 400 类错误不消耗配额。调用彻底失败时已扣的点会退回。