错误码

当出现错误时，你会收到对应的错误码，本文档将介绍和风天气API的错误码和错误信息。

提示：目前同时存在两种错误码版本，我们将陆续从v1版本迁移到v2版本，在此期间你会发现不同的API可能返回了不同版本的错误码。

注意：你应该妥善的处理遇到的错误，当错误发生时，请暂停请求并进行排查。你不应该放任错误的继续发生，否则这些错误的请求看起来是一种DDoS攻击，极端情况下，我们的安全策略可能冻结你的帐号。

错误码v2

v2版本将错误进行了细分和更加详细的描述，以便用户可以更容易了解错误的原因，同时也将HTTP Status Code与错误码保持了一致。

错误码包括以下类型：

INVALID PARAMETER

HTTP response status code: 400

错误的参数，一般指的是传入了错误的参数值，具体错误的参数请参考响应中的error.invalidParams。

MISSING PARAMETER

HTTP response status code: 400

缺失参数，当一些必选参数没有传递时将报错，具体缺失的参数请参考响应中的error.invalidParams。

NOT FOUND

HTTP response status code: 400

没有找到所查询的数据。例如查询一个不存在的城市或者一个错误的LocationID，此时你应该检查并更改查询的内容。

DATA NOT AVAILABLE

HTTP response status code: 400

数据暂时不可用。当你查询的数据超过我们支持的范围后将收到此错误码，例如查询一个地点的空气质量，而我们还不支持这个地点的空气质量，请尝试其他地点进行查询。

UNAUTHORIZED

HTTP response status code: 401

身份认证失败，你需要检查你的KEY或Token，考虑到安全因素，我们不会返回具体错误的原因。

NO CREDIT

HTTP response status code: 403

你的帐号内没有足够的可用额度、节省计划或其他额度，请求被拒绝。你需要先增加可用额度或购买其他额度之后再继续请求数据。

UNPAID

HTTP response status code: 403

由于你帐号内有未支付的欠款账单，请求被拒绝。你需要先完成欠款账单的支付再继续请求数据。

SECURITY RESTRICTION

HTTP response status code: 403

当前请求违反了你设置的请求限制，请求被拒绝，考虑到安全因素，我们不会返回具体违反了哪些请求限制。请检查：

• 该请求是否与你的请求限制有冲突
• 你的请求限制是否合理
• 若果请求不是你发送的，请考虑你的凭据可能已经泄露

ERROR HOST

HTTP response status code: 403

由于使用了错误的Host和凭据，请求被拒绝。例如使用免费订阅的凭据请求标准订阅服务，或使用标准订阅的凭据请求免费订阅服务。

ACCOUNT SUSPENSION

HTTP response status code: 403

由于用户帐号被冻结，请求被拒绝。了解帐号冻结。

FORBIDDEN

HTTP response status code: 403

你暂时无权限请求这个数据。你可以提交工单向我们了解相信信息。

404

HTTP response status code: 404

输入了错误的路径或错误的路径参数，无法找到该资源。请注意，404错误不会返回response body。

TOO FAST

HTTP response status code: 429

请求速度过快，超过了QPM限制。你需要暂停一小段时间再进行重试，同时如果你有多个设备，这个暂停的时间应该错开。请参考指数退避算法。

OVER FREE DAILY LIMIT

HTTP response status code: 429

超过了每日的免费请求量，此时你应该停止发送请求，等待到第二天再试。

OVER MONTHLY LIMIT

HTTP response status code: 429

对于包年包月订阅用户，当本月请求量超过限额后将收到此错误码，请等待至下个月再试，或者联系你的商务经理升级订阅方案。

UNKNOWN ERROR

HTTP response status code: 500

我们的服务发生了未知故障，请提交工单与我们联系。

响应

HTTP/2 400
Content-Type: application/problem+json

{
  "error": {
      "status": 400,
      "type": "https://dev.qweather.com/docs/resource/error-code/#invalid-parameters",
      "title": "Invalid Parameters",
      "detail": "Invalid parameters, please check your request.",
      "invalidParams": [
          "lang"
      ]
  }
}

• error.status 对应这个错误的HTTP status code
• error.type 这是一个URL用于标识错误类型
• error.title 对错误的简短描述
• error.detail 对错误的详细描述
• error.invalidParams 标识错误或缺失的参数

错误码v1

通过API接口中的code字段，可以获取到当前请求的状态，判断请求是否成功或出现错误。

响应

HTTP/2 200
content-type: application/json

{
  "code": "401"
}

1 vs 2

你可以简单参考下表了解v1和v2的差异，并快速的进行迁移。但是请注意，在我们完全迁移到v2之前，你还需要对v1进行兼容性设计。