Breaking change on 18-11-2026: new error format for quota and rate limits

On 18-11-2026, the error responses for quota and rate limits change to the JSON:API error format. Each error gets a fixed code and a link to the documentation.

This is a breaking change if your integration reads the body or the Content-Type of these errors. If it does, update your error handling.

What changes

Since 10-11-2026, two changes are already live:

  • 429 and 503 responses include a Retry-After header with the number of seconds to wait.
  • When the service is busy, the API returns 503 Service Unavailable instead of 429 Too Many Requests.

On 18-11-2026, the body and the Content-Type of these responses change as well.

ResponseMeaningOld detailNew code
403Quota used upQuota exceededquota_exceeded
429Rate limit exceededRate Limit Exceededrate_limit_exceeded
503Service busyAPI Rate Limit Exceededcapacity_exceeded

Other errors do not change.

Before 18-11-2026

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 2
{
  "type": "about:blank",
  "title": "Too Many Requests",
  "detail": "Rate Limit Exceeded",
  "status": 429
}

From 18-11-2026

HTTP/1.1 429 Too Many Requests
Content-Type: application/vnd.api+json
Retry-After: 2
{
  "errors": [
    {
      "status": "429",
      "code": "rate_limit_exceeded",
      "title": "Rate limit exceeded",
      "detail": "Too many requests per second ...",
      "links": { "type": "..." }
    }
  ]
}

The fields move into the errors array, and status is now a string. The 403 and 503 responses change in the same way.

Update your integration

  • Retry a 503 like a 429. Wait for the number of seconds in Retry-After, then retry.
  • Read the new format. Use errors[0].code to find the cause. Do not match on title or detail. These texts are for people and can change.
  • Handle the new Content-Type: application/vnd.api+json.
  • Check for quota_exceeded on a 403. Do not retry it automatically: wait until the quota renews. A 403 without this code means something else, usually that your key has no access to this API.

For how to handle each response, see Quota & Rate Limits.