API overload protection: Handling 429 errors

In order to respond quickly to your REST API calls—even when other customers are running time-consuming queries—New Relic includes overload protection in the API.

If you are querying a large enough amount of data to consume significant resources, the API's response code and headers will indicate that you have exceeded the capacity available for your API Key. This is a rare condition most customers will never see. Only customers whose API use is very resource-intensive will see it.

API response

Under normal operation, the API does not add any overload protection status to responses. You need not take any action.

Over the reporting period time interval, New Relic tracks each API request's impact on our system. If your API calls exceed the overload protection system’s threshold within a reporting period, the following things will happen:

  • Further API calls will fail with HTTP error code 429 (Too Many Requests)
  • The headers and body of the HTTP responses will contain more information about the error
  • API calls will be allowed again at the end of the reporting period


Here are the HTTP headers that will appear in API responses after you have exceeded the limit:

Overload header Meaning
NewRelic-OverloadProtection-Reset UNIX timestamp (number of seconds since Jan. 1, 1970) when the current reporting period ends. API requests will be responded to after this time.
NewRelic-OverloadProtection-Docs Hyperlink to this document so you immediately have additional information.


Here is an example API request indicating that the caller has consumed all of the available resources, and that further API calls will be allowed again at noon on Feb. 1, 2016:

curl -X GET 'https://api.newrelic.com/v2/applications.json' \
     -H 'X-Api-Key:${API_KEY}' -i
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
NewRelic-OverloadProtection-Docs: https://docs.newrelic.com/docs/apis/rest-api-v2/requirements/api-overload-protection-preventing-429-errors
NewRelic-OverloadProtection-Reset: 1454313600
NewRelic-OverloadProtection-UsagePercent: 100

  "error": {
    "title": "Too many resources consumed",
    "message": "Our API is a shared resource. In order to ensure good performance for all of our API users, overload protection has been enabled. For more information, please visit the article listed in the reference section.",
    "reference": "https://docs.newrelic.com/docs/apis/rest-api-v2/requirements/api-overload-protection-handling-429-errors"

At this point, New Relic will prevent your system from sending API calls for the rest of the reporting period, as noted in the NewRelic-OverloadProtection-Reset header. After the reporting period ends, your resource consumption will reset to zero, and API calls will be available to you again.

Preventing further 429 errors

The simplest remedy for a 429 error is to wait until the reporting period ends before sending your next API request. However, with careful management of your queries, you can avoid overload protection errors in the first place.

If you know you will be sending many resource-intensive queries, you can perform one of the following preventative measures:

  • Send your queries less often; in particular, query less frequently than once per minute (the refresh rate for agent data).
  • Cache data from New Relic rather than requesting it from the API every time.
  • Use the cursor-based technique if you must request metric names and the output results in multiple pages.

For more help

Recommendations for learning more: