「HTTP 状态码查询」是数据鱼API平台提供的状态码字典接口,Base 路径 /api/httpcode,共 6 个端点。库内收录 59 条状态码记录,按 1xx 至 5xx 五个类别组织,其中 1xx 有 4 条、2xx 有 8 条、3xx 有 7 条、4xx 有 29 条、5xx 有 11 条。每条记录包含编号、英文名、中文含义、所属类别与典型场景五个字段,既能整类拉取,也能按编号精确定位。
接口的价值在于把散落在各份 RFC 里的语义收敛成一份可编程的字典:调用方不必在代码里硬编码状态码含义,也不必为「这个 4xx 到底该不该重试」四处翻文档。列表与搜索返回精简字段,详情返回完整记录,两者的字段集合不同,接入时按用途选择。
方法 | 路径 | 说明 | 鉴权 |
|---|---|---|---|
GET | /api/httpcode/ping | 健康检查,返回版本与服务器时间,免鉴权 | 免鉴权 |
GET | /api/httpcode/stats | 返回总数与各类别条数统计 | 需要 |
GET | /api/httpcode/categories | 返回五个类别及其中文描述、条数 | 需要 |
GET | /api/httpcode/list | 按类别分页列出状态码,可按页码翻页 | 需要 |
GET | /api/httpcode/search | 按关键词检索编号、英文名、中文含义与场景 | 需要 |
GET | /api/httpcode/detail | 按编号返回单条完整记录 | 需要 |
鉴权用 X-API-Key 请求头或 ?api_key= 查询参数,缺失返回 4011,无效返回 4013。本接口全部端点均为 GET,参数只走查询串,不接受 JSON 请求体;请求体传参不会被解析,容易表现为「参数缺失」的 4001。响应统一为 {code, msg, data} 三段结构,code 为 0 表示成功。
本接口特有的错误分支集中在参数上:4001 表示缺少必填参数(如 detail 未传 code),4002 表示参数取值不合规(如 class 传了 6xx 或 abc),4004 表示该编号未收录。4040 与 4050 分别对应路由不存在与方法不允许,路径拼错时会返回前者而非参数错误,排查时先核对路径再核对参数。这是数据鱼API平台开发工具类接口的通用约定,换接口时可复用同一套错误处理分支。
/api/httpcode/search在编号、英文名、中文含义、典型场景四个字段上做不区分大小写的子串匹配,命中后返回精简字段列表。
参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
keyword | string | 是 | — | 搜索关键词,最长 64 字符 |
返回 total 为命中总数,items 为结果数组,每项含 code、name、cn、class 四个字段。关键词为空的请求直接返回 4001,超过 64 字符返回 4002;total 反映全部命中数,而 items 最多返回 100 条,需要完整结果时改用按类别分页的 list 端点。
GET /api/httpcode/search?keyword=timeout/api/httpcode/list按类别过滤并分页返回状态码,未传 class 时返回全部记录。
参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
class | string | 否 | — | 取值 1xx/2xx/3xx/4xx/5xx,其他值返回 4002 |
page | int | 否 | 1 | 页码,从 1 开始 |
page_size | int | 否 | 50 | 每页条数,上限 100 |
返回 total、page、page_size、items。page 小于 1 会被纠正为 1,page_size 超过 100 会被截到 100,非法分页参数不会报错而是静默回落默认值,调用方若依赖精确分页,应自行保证参数合法。
GET /api/httpcode/list?class=4xx&page=2&page_size=20/api/httpcode/detail按状态码编号取完整记录。
参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
code | int | 是 | — | 状态码编号,如 404 |
返回字段为 code、name、cn、desc、scene、class,比列表多出 desc(详细解释)与 scene(典型场景)。code 按整数解析,空值或非数字返回 4001,编号不在 59 条记录内返回 4004。API.md 的探测样例把 code 当作字符串传入,实际实现接受字符串形式的数字,"404" 与 404 等价。
GET /api/httpcode/detail?code=429page_size 上限 100,搜索单次返回上限同为 100 条。监控告警平台在错误日志里提取状态码后,用 detail 拉取中文解释,生成可读的告警文案。
网关或 SDK 在配置重试策略时,按类别判断 4xx 与 5xx,避免把客户端错误也纳入自动重试。
文档站点用 list 拉取全量数据,生成状态码对照表;新增状态码时只需重新拉取,不必改页面代码。
API.md 在 list 标注了一次探测失败:探测请求传入了不合规的 class 值,服务端返回 4002。该端点实际允许省略 class,省略时返回全部记录,接入时按 1xx 至 5xx 传值即可,不要照搬探测结果。
统计口径以字典收录数为准,某些状态码存在多个名称(如 413 与 414 的历史别名),本接口只保留主名称,不提供别名查询;需要匹配别名时应在调用方做映射。
状态码的语义由标准定义,但各服务端实现存在差异,例如 403 与 404 在部分系统里被混用、429 的 Retry-After 并非强制。本接口返回的是标准口径,判断线上问题时仍需以实际响应头与业务日志为准。数据鱼API平台不对据此做出的故障归因结论负责。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。