可以。无需登录或填写邮箱即可直接调用，这类用户在文档中统称为"访客"。

访客每月拥有 1500 积分 的免费额度。大多数基础接口单次调用消耗 1 积分，因此这份额度大约相当于每月 1500 次调用。

每月 1 号 0 点 自动重置，无需任何操作。

访客额度按 IP 地址（网络出口） 计算。因此，同一局域网下的多个设备会共享这 1500 积分的额度；切换网络后可能会获得一份新的额度，但这是非稳定行为，不建议在应用中依赖。登录账号之后，额度改为按账号计算，不再受 IP 影响。

当月额度用尽后，后续请求会被拒绝。访客月额度耗尽时通常返回 HTTP 429，并带有错误码 VISITOR_MONTHLY_QUOTA_EXHAUSTED，响应中会提示下一次可用时间；登录用户在免费额度、资源包和账户余额都不足时通常返回 HTTP 402，并带有错误码 INSUFFICIENT_CREDITS。如果希望立刻继续调用，可以登录账号将每月免费额度提升至 3500 积分，或前往 价格页 购买资源包（最低 ¥4.9，一次购买永久有效）。

登录之后，每月免费积分会从 1500 提升至 3500，默认调用速率也会从 4 QPS 提升至 7 QPS。同时可以在控制台查看详细的调用记录，并对 API Key 进行管理。

前往 价格页 即可购买。资源包一次购买永久有效，不会过期也不会按月清零，直至积分扣完为止。

会。命中缓存的请求按半价计费并向下取整，因此原价 1 积分的接口命中缓存后实际扣 0 积分，原价 2 积分的接口命中缓存后实际扣 1 积分，其它档位以此类推。某次请求是否走了半价，可以在响应头中确认。

支持缓存的接口及默认缓存时间如下。缓存时间可能因上游稳定性、数据更新频率或服务压力调整；如果接口没有出现在表中，应按不提供服务端缓存处理。GET /api/v1/misc/weather 的缓存会按请求 IP 区分，同一个城市参数在不同出口 IP 下可能不是同一份缓存。

查看响应头中的 X-Cache-Status 或 EO-Cache-Status。常见值包括 HIT（命中缓存）、MISS（未命中缓存，已重新请求上游）、STALE（返回过期缓存并在后台刷新）和 SKIP_UNCACHED（该请求未进入服务端缓存）。命中缓存并按半价计费时，响应头还会出现 UAPI-Credits-Pricing: cache-hit-half-price，实际扣费以 UAPI-Credits-Charged 为准。

TypeScript SDK 支持在请求参数中传入 disableCache: true。其它语言 SDK 的参数命名以对应 SDK 生成结果为准，使用前请查看该语言当前版本的接口示例；不要直接把 TypeScript 的驼峰字段照搬到所有语言噢。

TS

不使用 SDK 时，推荐在查询参数中追加一个每次不同的时间戳，例如 _t=Date.now()。服务端缓存键会包含查询参数，因此这种方式比只加 Cache-Control: no-cache 更可靠。

TS

QPS（Query Per Second）即每秒请求数上限。不同身份对应的默认 QPS 如下：

429 主要对应两种情况，需要结合响应中的 message / error 字段判断。

瞬时速率超限。 典型提示为 Visitor rate limit exceeded、Rate limit exceeded 或 Too many requests。此时响应头中会携带 Retry-After，客户端应按该值等待后再重试。推荐采用指数退避策略，例如依次等待 0.5s、1s、2s、4s 后重试。

当月免费额度已用尽。 典型提示为 VISITOR_MONTHLY_QUOTA_EXHAUSTED。本月额度需等到下月 1 号自动重置；如果希望立即继续调用，可以登录账号（每月 3500 积分）或购买资源包（¥4.9 起，永久有效）。

建议控制请求节奏，例如平均每分钟不超过 40 次；在重试逻辑中使用指数退避，避免无间隔循环重试；对于可以缓存的数据，在本端做一层缓存以减少调用。合理设计的应用通常不会触发限流，如果被限流，往往说明请求频率确实偏高。

402 表示账户的积分与余额均已扣完，仅登录用户可能触发。访客额度耗尽时返回的是 429 加 VISITOR_MONTHLY_QUOTA_EXHAUSTED，因此访客不会遇到 402。登录用户在收到 402 后，需要购买资源包或等待月初免费额度重置。

• 401：表示 API Key 无效、已过期、格式错误或已被删除。请检查 Key 是否完整，以及是否在控制台被删除。
• 403 CORS_FORBIDDEN：浏览器跨域调用接口时未携带 Key，处理方式参见 Q22。
• 403 IP not allowed / API path not allowed：当前请求不符合 Key 配置的 IP 白名单或接口白名单，请前往控制台调整 Key 的配置。

标准做法是在请求头中加入：

Authorization: Bearer 你的key

curl 示例：

BASH

Node.js：

JS

Python：

PYTHON

请前往控制台的 API Keys 页面。在该页面可以新建或删除 Key、为 Key 配置 IP 白名单、限定 Key 可调用的接口范围、设置独立的速率上限，以及查看每个 Key 的使用情况。

打开任意接口文档页即可看到 Playground。其认证方式位于参数区上方的下拉菜单，共有三个选项：

• 选择"不使用"时不携带 Key，按访客额度调用。
• 选择"当前账号"（登录后显示头像与用户名）时，自动使用当前账号的额度，无需手动粘贴 Key。
• 选择"自定义 Key"时，需粘贴自定义 API Key，该 Key 会保存在浏览器本地存储（localStorage）中，下次打开仍然可用，且可以随时清除。

请立即前往 API Keys 页面 删除该 Key 并新建一个。删除完成后，使用旧 Key 发起的调用会立即返回 401。

这是按策略设计的行为，而非异常。具体规则如下：

• 同站调用（例如 uapis.cn 官方页面中发起的调用）直接放行
• 跨域调用 /api/v1/* 时必须携带 Key，否则会返回 403 CORS_FORBIDDEN
• 非 /api/v1/* 的开放资源按默认策略放行

推荐通过自有后端转发：浏览器只调用自己的后端，由后端携带 Key 再调用 UAPI。这种方式的好处是 Key 不会暴露在前端代码中，同时可以在后端自行做缓存和二次限流。

若仅用于临时 Demo，也可以在前端 fetch 中直接加入 Authorization: Bearer 你的key 调用。但需要注意，任何访问者都能通过浏览器开发者工具获取到该 Key，存在被滥用的风险，不建议用于正式环境。

请参考 Q21 立即删除并重建 Key。后续建议严格采用自有后端转发的接入方式，避免在前端 JS 中硬编码 Key。

控制台内各项信息的入口如下：

页面会以进度条的形式展示"已用 XX%"，额度不足时也会给出提示。

每次请求的响应头中都会返回相关信息，重点关注两个响应头：RateLimit-Policy 表示当前生效的上限，RateLimit 表示剩余量与恢复时间。响应头中包含多个“桶”（bucket），常见的桶名及其含义如下：

例如，响应中取得：

RateLimit: "billing-quota";r=2800;uapi-unit="credits";t=86400,"billing-balance";r=860;uapi-unit="cents";t=45

即表示资源包剩余 2800 积分，账户余额为 860 分，即 8.6 元。

可以直接用 curl 查看响应头：

BASH

对比输出中的 RateLimit 与 RateLimit-Policy，即可获得剩余额度的信息。

不会。只有 2xx 成功响应才会计费，4xx 与 5xx 响应（业务性 404 除外）均不计费。

可以通过以下响应头确认：

其中 UAPI-Debit-Status 的可能取值如下：

并非多扣。通常是 Charged < Requested，表示命中缓存后按半价计费。例如原价 1 积分的接口命中缓存时，Requested=1 而 Charged=0；原价 2 积分的接口命中缓存时，Requested=2 而 Charged=1。

当前的错误响应并非单一格式，不同接口存在一定差异，客户端需要做兼容处理。常见的结构主要有以下几种。

1. 标准错误结构（最常见）

JSON

2. 简化错误结构，没有 code，只有 error：

JSON

3. 积分不足或访客月额度耗尽，会携带跳转链接：

JSON

4. 限流类错误，其中 code 为数字：

{ "code": 429, "message": "Rate limit exceeded", "limit": 10 }

推荐的读取顺序是：优先读取字符串形式的 code，若不存在则读取 error 字段；message 原样保留展示，不要覆写；同时建议保留响应头 X-Request-ID，以便后续排查。

以下是常见错误码及其含义与处理建议：

总体上，400 / 401 / 403 / 404 属于客户端错误，应修正请求后再发起，不要直接重试；500 / 502 / 503 / 504 以及 429 属于服务端或限流错误，可以在退避后重试。

以下为常见状态码的对应处理方式：

这类错误在尚未取得 HTTP 状态码前就已经失败，通常属于客户端或网络层的问题。常见情况如下：

临时性问题通常可以重试，包括 429（按 Retry-After 等待后重试）、408、500、502、503、504，以及网络层超时类错误（如 ECONNABORTED、ETIMEDOUT）。而 400、401、402、403、404、413 属于客户端自身的问题，重试也不会成功，应当在修正后再发起。

推荐的指数退避实现如下：

JS

最关键的是响应头中的 X-Request-ID，每次请求都会返回。除此之外，还建议提供出问题请求的 URL 与请求方法（请勿包含 Key）、HTTP 状态码与返回的 JSON，以及大致的时间点（建议精确到分钟）。如果没有 X-Request-ID 也能排查，但效率会明显下降。

可以。SDK 会自动完成 HTTP 状态映射、错误对象解析、基础重试等工作，支持的语言列表见 错误处理指南，按语言安装对应包即可使用。如果使用 curl、fetch 或 requests 直接调用，则需自行按 Q31–Q35 完成字段兼容与重试逻辑。

可以长期使用。免费部分会保持免费：访客每月 1500 积分、登录用户每月 3500 积分，均在每月 1 号自动发放。资源包仅在用户主动购买时收费，不存在自动扣款，且资源包一次购买永久有效、扣完即止，没有订阅机制。

不建议。1500 积分每月的额度容易耗尽，4 QPS 的速率在并发略高时即会触发 429；访客没有账号归属，出现问题时难以定位；访客按 IP 计算，服务器 IP 变更会导致用量断档。因此生产环境至少应使用登录账号，对稳定性有要求时建议购买资源包（¥4.9 起）。

可以。在 API Keys 页面 中，可以为每个 Key 配置两类限制：速率限制（每秒、分、时或天内最多调用的次数），以及单 IP 速率限制（每个调用方 IP 在每秒、分、时或天内最多调用的次数）。

为便于统一表达，对外按"次 / 窗口"换算。例如 10 次/秒 即 10 QPS，120 次/分 相当于平均 2 QPS，86400 次/天 相当于平均 1 QPS。