错误码

通用规则

接口通过 HTTP 状态码表达传输状态，通过 JSON code、message、error、next_action 表达业务状态。

调用方应展示可恢复建议，不应把错误信息扩写成接口未返回的承诺。

统一错误响应候选

{
  "code": 1001,
  "message": "Missing required field: query",
  "error": {
    "type": "validation_error",
    "retryable": false,
    "field": "query",
    "http_status": 400
  },
  "next_action": "ask_user_for_missing_route_or_query",
  "request_id": "available_when_provided",
  "privacy_flags": {
    "contains_private_contact": false,
    "raw_qr_exposed": false,
    "internal_path_exposed": false
  }
}

业务错误码

0     成功
1001  参数缺失或格式错误，常见于缺少 query、departure/destination 或 info_id
1002  未找到结果或目标资源不存在/不可展示
2001  未授权或 API Key 无效
2002  权限不足
429   调用过快或触发限流
5000  上游超时或临时不可用
5001  服务端异常

HTTP 状态参考

200   请求已被接口处理，需继续读取 JSON code 判断业务状态
400   参数缺失或格式错误，通常对应 code=1001
401   未授权，通常对应 code=2001
403   权限不足，通常对应 code=2002
404   目标资源不存在或不可展示，通常对应 code=1002
429   调用过快或触发限流，通常对应 code=429
502   上游临时不可用，通常对应 code=5000
504   上游超时，通常对应 code=5000
500   服务端异常，通常对应 code=5001

调用方处理建议

• 参数缺失：提示用户补充出发地、目的地、日期或 info_id。
• 无查询结果：如果接口返回相关官方拼车群，可直接展示群入口；不要自行编造拼车信息。
• 权限或隐私边界：停止调用，不通过其他工具绕过限制。
• 限流：降低重试频率，避免连续探测同一路线或同一工具。
• 服务异常：提示稍后再试，不编造替代结果。