错误

错误始终以 RFC 9457 application/problem+json 格式返回：

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://docs.grem.capital/api/errors/business_rule",
  "title": "business_rule",
  "status": 422,
  "detail": "Describe the property: pick a listing or fill in at least a description, city or area",
  "code": "not_enough_input",
  "requestId": "req_..."
}

带字段的校验错误：

{
  "title": "validation",
  "status": 400,
  "detail": "\"avatarId\" is required",
  "errors": [{ "field": "avatarId", "message": "\"avatarId\" is required" }],
  "requestId": "req_..."
}

错误码

type 中的 URL 指向本列表中对应的条目。

invalid_key

401。密钥缺失、错误、已撤销或已过期。请检查 Authorization 请求头以及后台中的密钥状态。

forbidden_scope

403。密钥有效但缺少所需的权限范围。请添加权限范围或创建新密钥（认证）。

forbidden

403。该账户或资源不允许此操作：例如房源属于其他账户，或在机构中的角色不够。原因见 detail。

insufficient_funds

402。钱包余额不足、套餐额度已用完、有未付欠款或已达到合理使用上限。code 说明是哪一种：INSUFFICIENT_FUNDS、QUOTA_EXCEEDED、DEBT_OUTSTANDING、FAIR_USE_LIMIT_REACHED 等。请充值、还清欠款或更换套餐。

validation

400。请求未通过校验。具体问题见 detail 和 errors。请修正请求；原样重试没有意义。

business_rule

422。请求格式正确但无法执行：缺少数据、房源状态不合适、不支持该物业类型等。原因见 detail，机器码见 code。

payload_too_large

413。请求体或文件超过上限。大小限制在各工具中注明。不是有效 JSON 的请求体返回 400 validation。

range_not_satisfiable

416。文件下载的 Range 超出了文件范围。Content-Range: bytes */size 给出文件大小。

rate_limited

429。超过请求频率限制。等待 Retry-After 指定的秒数后重试（限制与计费）。code 说明是哪个上限：minute_limit（秒级）或 daily_limit（00:00 UTC 重置）。

not_found

404。未知路径，或资源不存在、不属于您。他人的资源会刻意返回与不存在资源相同的响应。

idempotency_conflict

409。使用该 Idempotency-Key 的请求仍在执行。等待其完成后用同一个键重试（幂等性）。超时（502 provider_error）后该键会保留 15 分钟：重试前请先查看结果，保留期过后重试会再次执行付费工作。快速估价在超时后会释放该键：请用同一个键重试。当使用该键的调用仍在预留付款时（code 为 RESERVE_IN_PROGRESS、RESERVE_BUSY）也会返回同样的 409，请稍后重试；RESERVE_REF_TAKEN 表示该键已用尽，请换一个新键。

conflict

409。资源当前的状态不允许此操作（例如将房源从一个机构直接转到另一个机构、删除有生效佣金合同的房源）。原因在 detail 中。不要原样重复该请求。

service_unavailable

503。工具暂时不可用。未扣任何费用。等待 Retry-After 后重试；GET /tools/status 显示工具的当前状态。

provider_error

502。执行任务的服务出错。属于临时问题：以递增的间隔重试。如果 detail 表明工具未及时响应，工作仍可能完成并被计费：再次启动前请先查看 GET /works；快速估价请使用同一个 Idempotency-Key 重试。照片优化、网站和草稿的结果不会保存在 GET /works 中：对它们请等 15 分钟保留期结束，并在后台或您的房源中查看结果。

internal_error

500。内部错误。稍后重试；如果持续出现，请携带 requestId 联系支持。

列表可能扩充。请把未知错误码当作其 HTTP 类别的一般错误处理（4xx 为请求问题，5xx 为服务故障）。

哪些需要重试

重试会创建内容的请求时，请始终发送同一个 Idempotency-Key：这样重试既不会重复执行，也不会重复扣费。

例外

• 当前线索状态不允许的 Swipe Match 事件（POST /match/leads/{id}/events）返回 409，title: business_rule，原因在 code 中（client_event_rejected、invalid_transition、not_available）。
• 使用个人密钥或角色不足时，机构线索池操作（POST /leads/{id}/claim、POST /leads/{id}/return-to-pool）返回带 title: forbidden 的 403。

哪些不收费

被拒绝的请求（任何 4xx 或 5xx 响应）不消耗 API 调用。工具价格只对被接受的工作收取。例外是超时后的 provider_error：工作可能仍会完成并扣费，重新启动前请先查看 GET /works（照片优化、网站和草稿：在后台或您的房源中查看）。

相关文章

• 限制与计费
• 幂等性
• 认证