适用场景

在企业应用开发中，经常需要通过企业名称关键词查询工商信息，用于客户背景调查、供应商审核、合规检查等场景。企业工商信息查询API（company-search）提供基于天眼查权威数据的实时匹配服务，返回前5条最匹配结果。本文重点分析该API的常见错误模式，帮助开发者高效排错，避免在生产环境中因接口异常导致业务中断。

接口能力边界

• 请求方法：GET
• 请求地址：https://v1.apizero.cn/api/company-search
• 分类：身份核验
• QPS限制：5次/秒（超过限制会返回429状态码）
• 数据缓存：6小时，故新准备企业的数据可能延迟更新
• 匹配规则：按上游评分排序，每次最多返回5条结果
• 匿名额度：不传X-API-Key可走匿名额度，但QPS和总量受限（具体以官方文档为准）

请求参数与鉴权

Query参数

Header参数

注意：name不能为空，不能全为空格，长度必须在2~50字符之间。超出范围或无效字符会导致400错误。

curl接入与错误模拟

以下是标准请求示例（使用环境变量$APIZERO_API_KEY代替实际Key，请替换）：

curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/company-search?name=腾讯科技"

模拟常见错误

1. 缺少必要参数

# 不传name参数 curl -sS -X GET -H "X-API-Key: $APIZERO_API_KEY" "https://v1.apizero.cn/api/company-search" # 返回400，msg类似“参数name不能为空”

2. name长度不足或过长

# name=“A”（单字符） curl -sS -X GET -H "X-API-Key: $APIZERO_API_KEY" "https://v1.apizero.cn/api/company-search?name=A" # 返回400，msg提示参数长度需在2~50之间

3. 未携带有效API Key（匿名额度耗尽或Key错误）

# 使用错误Key，或匿名额度已用完 curl -sS -X GET "https://v1.apizero.cn/api/company-search?name=腾讯科技" -H "X-API-Key: invalid123" # 可能返回403（Forbidden）或401（Unauthorized），具体以实际响应为准

响应字段解读

成功返回HTTP 200，响应体为JSON格式，示例：

{ "code": 0, "data": { "keyword": "腾讯科技", "total": 20, "list": [ { "id": 1466562059, "name": "广州腾讯科技有限公司", "legal_person": "邬红波", "credit_code": "91440101327598294H", "reg_capital": "7000万人民币", "reg_status": "存续", "establish_time": "2014-12-31", "business_scope": "电子;通信与自动控制技术研究...", "city": "广州市", "district": "海珠区", "reg_location": "广州市海珠区新港中路397号...", "phone": "020-81167888", "email": "service@tencent.com", "category": "研究和试验发展", "company_org_type": "有限责任公司", "english_name": "Guangzhou Tencent Technology Co., Ltd.", "logo": "https://img5.tianyancha.com/logo/lll/...", "history_names": "", "match_field": "股东信息" } ] }, "msg": "成功", "request_id": "mota..." }

关键字段：

• code: 0表示成功，非0表示业务异常（见错误表）。
• data.total: 匹配到的企业总数（非结果集数量，结果集最多5条）。
• data.list: 企业对象数组，每个对象包含工商准备的核心字段。注意reg_capital为字符串（如“7000万人民币”），不是数字，使用前需按需转换。
• match_field: 匹配方式（如“股东信息”、“企业名称”），可用于调试匹配质量。
• request_id: 每个请求的唯一标识，排查问题时提交给技术支持用。

常见错误场景与排错指南

1. HTTP 400 Bad Request —— 参数错误

可能原因：

• name参数缺失、为空字符串或全为空格。
• name长度小于2或大于50个字符。
• 字符包含非法控制字符或未进行URL编码（如输入中文时忘记编码，但现代curl会自动处理，手动拼接URL时需注意）。

排查方法：

• 检查请求URL中name是否为预期值，可以用--data-urlencode方式（对GET请求使用-G）：

  curl -G -sS -H "X-API-Key: $APIZERO_API_KEY" \ --data-urlencode "name=腾讯科技" \ "https://v1.apizero.cn/api/company-search"

• 确认字符串前后无不可见字符。
• 查看响应msg字段的具体提示。

2. HTTP 401/403 —— 鉴权失败或匿名额度超限

可能原因：

• 未传递X-API-Key且匿名QPS/每日调用量已耗尽。
• 传递的Key无效、过期或被冻结。
• 请求IP不在白名单（如果有白名单限制）。

排查方法：

• 确认Key正确且处于有效状态，可到控制台重新生成。
• 检查请求Header大小写：正确为X-API-Key（区分大小写）。
• 尝试传递一个有效Key后重试，若仍403，检查IP是否被限制。
• 查看响应body中的msg或code字段（部分错误会返回更详细描述）。

3. HTTP 429 Too Many Requests —— QPS超限

可能原因：

• 同一时间发起大量并发请求，超过5 QPS的阈值。
• 没有合理使用本地缓存或限流策略。

排查方法：

• 检查响应Header中的Retry-After（单位秒），等待后重试。
• 实现客户端限流：使用令牌桶算法或简单的队列+延迟。
• 在请求间添加至少200ms间隔（1秒5次相当于每次200ms）。
• 如果业务需要更高QPS，可申请提高限额（以官方渠道为准）。

4. HTTP 500 Internal Server Error —— 服务端异常

可能原因：

• 上游数据源临时不可用。
• API服务自身bug或过载。

排查方法：

• 等待几秒后重试，通常为临时故障。
• 检查响应中request_id，提交给技术支持时包含该ID。
• 实现指数退避重试（如首次100ms，后续递增至3秒，最多3次）。

5. 业务错误码（code非0）

响应体中code非0时，msg给出原因。常见业务错误：

注意：部分场景下未传递X-API-Key时，响应中的code可能为1004并提示。

6. 返回数据为空（list=[]）但仍返回200

原因：关键词匹配不到企业。这不属于错误，但开发者常误以为是接口问题。

排查方法：

• 尝试更精确的企业全称。例如搜“腾讯”可能返回大量结果，搜“腾讯科技”精准度更高。
• 考虑企业可能未收录（缓存6小时，新准备企业需等待）。
• 检查data.total为0时确认无匹配。

工程化注意事项

1. 请求重试策略

对于HTTP 429和5xx，采用指数退避重试：

import time import requests url = "https://v1.apizero.cn/api/company-search" headers = {"X-API-Key": "YOUR_KEY"} params = {"name": "腾讯科技"} max_retries = 3 retry_delay = 0.2 # 初始200ms for attempt in range(max_retries): resp = requests.get(url, headers=headers, params=params) if resp.status_code == 200: break elif resp.status_code == 429 or resp.status_code >= 500: time.sleep(retry_delay * (2 ** attempt)) else: # 400/401/403 直接失败，无需重试 raise Exception(f"HTTP {resp.status_code}: {resp.text}")

2. 参数编码与校验

• 始终对name进行URL编码，尤其包含空格、特殊符号时。
• 在客户端提前校验name长度（2~50）和字符类型（建议只传中英文、数字、括号，避免不可见字符）。
• 使用requests库时直接传递params字典，库会自动编码。

3. 并发控制

• QPS=5意味着200ms内最多1次请求。若需并发查询多个企业，应使用队列或信号量限制：

import asyncio import aiohttp semaphore = asyncio.Semaphore(5) # 每秒最多5个，实际需配合时间窗口 async def fetch(session, name): async with semaphore: async with session.get(url, params={"name": name}, headers=headers) as resp: return await resp.json()

更严格的限流应使用令牌桶。

4. 缓存策略

由于数据6小时缓存，对同一企业的重复查询结果一致。建议在应用层建立短时缓存（例如将查询结果缓存5分钟），避免浪费请求次数和超限。

5. 日志与监控

• 记录每次请求的request_id、name、HTTP状态、响应时长、total值。
• 监控HTTP 429频率，及时调整并发策略或申请扩容。
• 出现5xx时及时告警，并检查是否是服务端故障。

6. 字段类型注意

• reg_capital和reg_status为字符串，不要直接做数值比较。如需提取数值，先解析（如“7000万人民币”转数值时需处理“万”单位）。
• establish_time格式为YYYY-MM-DD，可直接作为日期字符串处理。
• phone和email可能为空字符串，取值时做非空判断。

参考文档

• 企业工商信息查询 API 官方文档
• 原始接口文档（Markdown）