错误与状态码

错误以 JSON 返回，结构始终一致，并且总是带有稳定的机器可读代码。请依据代码分支，而不是依据消息。

结构

每一次失败都会返回一个对象，其中包含供人阅读的 error 和稳定的 code。消息是写给人看的，可能会被改写；代码是一项约定，不会在你不知情时改变。

{
  "error": "That file is larger than the 200 MB limit on your plan.",
  "code": "VALIDATION_FAILED"
}

429 与 500 值得延迟后重试 —— 请采用退避而不是死循环，因为重试和其他请求一样会计入你的每小时限制。

其余的对该请求而言都是终局。重试 400、402 或 404 只会得到相同的答案，并为此消耗你的频率额度。

没有 JSON 主体的 502 或 503 并非来自应用本身 —— 那是它前面的代理，那种情况下重试总是值得的。