首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API · HTTP 状态码查询接口接入指南

数据鱼API · HTTP 状态码查询接口接入指南

原创
作者头像
用户12862874
发布于 2026-11-21 21:33:21
发布于 2026-11-21 21:33:21
430
举报

接口简介

「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 端点。

代码语言:javascript
复制
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,非法分页参数不会报错而是静默回落默认值,调用方若依赖精确分页,应自行保证参数合法。

代码语言:javascript
复制
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 等价。

代码语言:javascript
复制
GET /api/httpcode/detail?code=429

数据与限制

  • 收录总量 59 条,类别分布为 1xx 4 条、2xx 8 条、3xx 7 条、4xx 29 条、5xx 11 条。
  • page_size 上限 100,搜索单次返回上限同为 100 条。
  • 搜索关键词长度上限 64 字符,按字符计而非字节。
  • 记录为静态字典,随 HTTP 标准演进由服务端统一维护,调用方无需增量同步。

典型使用场景

监控告警平台在错误日志里提取状态码后,用 detail 拉取中文解释,生成可读的告警文案。

网关或 SDK 在配置重试策略时,按类别判断 4xx 与 5xx,避免把客户端错误也纳入自动重试。

文档站点用 list 拉取全量数据,生成状态码对照表;新增状态码时只需重新拉取,不必改页面代码。

注意事项

API.md 在 list 标注了一次探测失败:探测请求传入了不合规的 class 值,服务端返回 4002。该端点实际允许省略 class,省略时返回全部记录,接入时按 1xx 至 5xx 传值即可,不要照搬探测结果。

统计口径以字典收录数为准,某些状态码存在多个名称(如 413 与 414 的历史别名),本接口只保留主名称,不提供别名查询;需要匹配别名时应在调用方做映射。

状态码的语义由标准定义,但各服务端实现存在差异,例如 403 与 404 在部分系统里被混用、429 的 Retry-After 并非强制。本接口返回的是标准口径,判断线上问题时仍需以实际响应头与业务日志为准。数据鱼API平台不对据此做出的故障归因结论负责。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 关键词搜索 /api/httpcode/search
    • 分页列表 /api/httpcode/list
    • 单条详情 /api/httpcode/detail
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档