亿牛云API代理开发手册
1. 接入与调用
获取示例代码
请访问 代码示例 & SDK 下载，选择适合的语言和请求库。这个页面主要服务已经接入过 API 代理、需要快速查参数和排障的用户，因此后续内容默认围绕“调用格式、接口参数、错误定位”展开。
API 链接格式
API 代理通过 URL 链接直接提取代理 IP。使用前请先确认服务器 IP 已加入白名单。
1http://ip.16yun.cn:817/myip/pl/1118b93d-1d4b-4886-8bf6-00e16a13ed30/?s=vechdrlmwm&u=testuser&format=json
返回格式
默认格式、JSON 格式 和 自定义分隔符 是最常见的三种返回方式。它们属于同一类“输出格式”设置，不再分散写在快速开始里。
默认返回一行一个代理 IP，格式为 ip:port，适合直接导入程序或脚本中使用。
161.12.1.1:36986
如果只是快速验证 API 是否成功返回代理资源，默认格式通常最直接。
2. 接口速查
这一部分只保留最常用的 API 参数和白名单操作，方便快速定位，不再混入排障说明。
提取参数
| 功能 | 参数示例 | 说明 |
|---|---|---|
| 获取指定数量代理 IP | &count=[数量] | 超过最大值时，返回最大数量。 |
| 获取指定索引代理 IP | &index=[索引位置] | 返回指定位置的代理 IP。 |
| 限制时间范围内提取量 | &countkey=d&countlimit=[总量] | 限制天、小时或分钟内的提取总量。 |
白名单管理
| 功能 | 参数示例 | 说明 |
|---|---|---|
| 获取白名单 | &limitip=get | 查看当前白名单 IP。 |
| 添加白名单 | &limitip=append&newip=[ip] | 添加新 IP 到白名单。 |
| 替换白名单 | &limitip=replace&newip=[newip]&oldip=[oldip] | 替换指定 IP。 |
| 覆盖白名单 | &limitip=cover&newip=[ip1]&newip=[ip2] | 用新 IP 覆盖当前白名单。 |
3. 运行与错误码
这一部分只保留最常见、最影响调用结果的状态码，其他错误请继续查看 HTTP 错误码说明。
| 状态码 | 含义 | 优先动作 |
|---|---|---|
| 403 | IP 白名单错误 | 检查当前出口 IP 是否已录入白名单，动态 IP 场景确认是否开启自动更新。 |
| 429 | 请求频率过高 | 降低请求速率，减少线程数或并发数。 |
| 450 | 访问了不允许的网站 | 仅 API 包量产品可能出现。确认目标域名是否在允许范围内，如需放开请联系 。 |
| 504 | 目标网站不可达或代理切换中 | 先确认目标网站在不使用代理时是否可访问，再检查请求头和目标站防护策略。 |
NOTE
406：当前没有可用代理可提取。408：请求超时，通常和网络质量或目标网站响应速度有关。- 如需完整错误码说明，请查看 HTTP 错误码说明。
4. 故障排查
先按现象或状态码定位问题，再做最短路径排查。若流程图定位后仍未解决，请继续查看 HTTP 错误码说明。
Loading diagram...
第一步：用 curl 验证 API 链路
先确认 API 链路本身是否能正常返回代理结果，再继续排查业务代码。
1#!/bin/bash2curl "http://ip.16yun.cn:817/myip/pl/xxx/?s=xxx\&u=testuser\&format=json"
排查动作
API 链接打不开
- 优先检查 API 链接是否完整，尤其是
s、u、format等参数是否拼接正确。 - 再检查当前服务器网络、DNS 解析以及白名单配置。
返回 403，说明白名单失败
- 确认当前出口 IP 是否已加入白名单。
- 动态 IP 场景下，确认白名单是否已更新到最新 IP。
返回 429，说明请求频率过高
- 降低 API 链接访问速度。
- 多线程或多进程场景下，按总请求量而不是单线程速率计算。
返回 450，说明访问了不允许的网站
- 这个状态码只会出现在 API 包量产品中。
- 先确认目标网站是否属于不允许访问的域名；如确有业务需要，请联系 申请放开。
返回 504，说明目标站不可达或代理切换中
- 少量 504 属于正常波动。
- 如大量出现，请先在不使用代理的情况下检查目标网站是否可访问，再补充
cookie、referer、user-agent等必要请求头。
返回格式不符合预期
- 检查是否正确拼接了
&format=json或&part=分隔符。 - 如果使用 curl 或浏览器手动测试，注意链接中的特殊字符是否已经正确转义。
5. 常见问题
API 链接能打开，但返回的不是 JSON
- 请确认链接中已添加
&format=json。 - 若手动拼接了多个参数，请检查 URL 是否缺少转义导致参数失效。
白名单更新后，仍然返回 403
- 先确认当前程序运行出口 IP 是否和你更新到白名单中的 IP 一致。
- 如果服务器使用动态 IP，请优先开启自动更新，避免白名单滞后。
返回少量 504，但程序大部分请求正常
- 这种情况通常属于目标网站波动或代理切换中的短时现象。
- 如果只是少量出现，可先观察；如果持续放大，再按排障流程检查目标网站可达性和请求头配置。
需要继续分析完整错误码
- 若流程图和本页速查仍然不足以定位问题，请继续查看 HTTP 错误码说明。