实时公交到站接口排错手记：从 401 到 429 的完整排查路径

适用场景与接口能力边界实时公交到站接口用于输入城市和站名查询该站各公交线路的到站信息包括车牌、预计到站时间、剩余站数、票价和终点方向。典型使用场景有出行助手的数据源、公交小程序、生活服务集成、电子站牌类展示页等。接入前先明确接口能力边界避免在设计阶段就埋下排错隐患请求方法POST请求地址https://v1.apizero.cn/api/bus-realtimeQPS 限制10 / s方向支持direction传 1 为默认方向2 为反方向覆盖城市数百城市具体城市列表以文档为准实际排查中错误通常分为两个层次HTTP 层错误401、400、429、5xx和业务层错误HTTP 200 但code非 0、data为空或数据过期。下面按这两条路径展开。请求参数与鉴权Header 参数参数是否必填类型说明Content-Type是string固定为 application/jsonX-API-Key是string接口鉴权密钥请求体字段字段类型必填说明citystring是城市名例如「长沙」stationstring是站名或关键词兼容别名linedirectionnumber否1默认方向2反方向这里有一个容易踩的类型坑direction的声明类型是 number。如果前端框架把参数统一处理成 string例如1部分网关会直接返回 400部分会做隐式转换。建议在代码层强制统一为整数。curl 接入示例curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {city: 长沙, station: 五一广场, direction: 1} \ https://v1.apizero.cn/api/bus-realtime把$APIZERO_API_KEY替换为实际密钥后正常响应如下{ code: 0, data: { city: 长沙, direction: 1, line_count: 2, lines: [ { line: 401路, terminal: 汽车西站, price: 2, bus_count: 1, buses: [ { bus_id: 湘A02882D, arrival_time: 2026-07-01 12:34, arrival_timestamp: 1751344440000, stops_remaining: 5, travel_minutes: 6, status: 5站 } ] } ], station: 五一广场, updated_at: 2026-07-01 12:30:00 }, msg: 成功, request_id: a1b2c3d4 }返回字段解读code业务状态码0表示成功。msg提示信息。request_id请求唯一标识排错时需要提供给接口提供方。data.line_count返回线路数量。data.lines[].line线路名。data.lines[].terminal终点方向。data.lines[].price票价。data.lines[].bus_count该线路当前可查询到的车辆数。data.lines[].buses[].bus_id车牌号。data.lines[].buses[].arrival_time预计到站时间可读格式。data.lines[].buses[].arrival_timestamp预计到站的毫秒时间戳。data.lines[].buses[].stops_remaining剩余站数。data.lines[].buses[].travel_minutes预计还需分钟数。data.lines[].buses[].status到站状态文本摘要。data.updated_at数据更新时间。一个常见的排错误区是直接拿status文本做前端逻辑判断。status的语义可能随上游调整建议以stops_remaining数字和arrival_timestamp时间戳作为判断依据status只用于展示兜底。常见错误与排错路径401 Unauthorized鉴权失败现象HTTP 401msg类似invalid api key。排查顺序确认请求头是否携带X-API-Key注意大小写和连字符。确认密钥是否复制完整末尾空格是高频失误。确认环境变量在当前 shell 中是否已导出echo ${APIZERO_API_KEY:已设置}输出为空则说明环境变量未生效先export再执行 curl。400 Bad Request请求体格式错误现象HTTP 400通常是Content-Type或 JSON 语法问题。检查-d中的 JSON 是否合法高频错误包括JSON 键名使用了单引号不符合标准。中文字符被错误转义。对象末尾出现尾逗号。可以先本地校验再发请求echo {city:长沙,station:五一广场,direction:1} | jq .jq能正常解析再用原样内容发起请求。422 / 参数校验错误必填字段缺失现象HTTP 200 但业务code非 0msg提示缺少city或station。两类典型原因字段名拼写错误例如把station写成stations。字段值为空字符串{city: , station: 五一广场}网关通常视为已传但无效。建议在业务代码里先做本地校验空值直接拦截不发出请求。业务 code 非 0 但 HTTP 200HTTP 200不代表查询成功。必须同时判断code 0且data存在。这类错误容易被简单封装吞掉是集成中最隐蔽的一类问题。排查方向站名是否为正式站点名尝试换成短关键词。城市名是否在支持列表内以文档为准。是否存在同名站部分城市需要更精确的关键词。429 Too Many Requests请求频率超限现象HTTP 429提示限流。接口 QPS 为 10 / s多线程或高并发场景容易触发。处理方案客户端做令牌桶限流把峰值控制在 8 QPS 以内。对 429 做退避重试例如sleep 500ms后重试最多两次。增加应用层短缓存避免每次用户刷新都打接口。5xx服务端异常现象502、503、504。通常是网关或上游数据源波动。处理原则设置合理 HTTP 超时时间建议 5 秒。5xx 可重试但重试间隔要加随机抖动避免集中重试放大压力。数据一致性排错响应成功但数据可疑这是排错中最容易忽略的一层。即使code 0也要做数据合理性检查updated_at与当前时间差超过 5 分钟应降级展示并标记为非实时数据。arrival_timestamp小于当前时间说明班次已到站不要再渲染「即将到达」。buses为空数组表示该线路当前暂无车辆数据属于正常状态但 UI 必须提供无数据态。工程化注意事项参数类型统一direction声明为 number但前端框架传参常为 string。在请求组装处统一规整const payload { city: params.city, station: params.station, direction: Number(params.direction ?? 1), };错误分类与重试策略建议把错误分成三类客户端错误400 / 422 / 401记录响应体到日志提示调用方修改参数。限流错误429退避重试。服务端错误5xx短暂重试加降级。缓存与监控同一站点的到站信息在 30 秒内变化有限可加 15 到 30 秒短缓存降低 QPS 压力。日志中记录request_id、code、updated_at便于跨端对齐问题。对updated_at与本地时间的差值做监控超过阈值触发告警这能及时发现数据源异常。参考文档接口文档https://apizero.cn/aidocs/bus-realtime原始文档https://apizero.cn/aidocs/bus-realtime/raw.md