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.

Customers will be limited to 1000 API calls per minute.

API responses

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.

These are the typical cases that can trigger overload protection or rate limiting:

• An API key you're using has exceeded the maximum number of requests per minute.
• Our system is generally overloaded, and we need some accounts decrease their reporting.

In a case where rate limiting occurs, the following things will happen:

• Further API calls will fail with HTTP status code 429 (too many requests).
• The headers and body of the HTTP responses may or may not contain more information about the error.
• API calls will be allowed again at the end of the reporting period.

Headers

Here are the HTTP headers that will appear in API responses if you have exceeded your API key's individual limit:

Here are the HTTP headers that will appear in API responses if there is a general system problem:

Example

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 "Api-Key:$API_KEY" -i
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
...
X-RateLimit-Docs: https://docs.newrelic.com/docs/apis/rest-api-v2/requirements/api-overload-protection-preventing-429-errors
X-RateLimit-Reset: 1454313600
X-RateLimit-Remaining: 0
X-RateLimit-Limit: 1000

{}

Preventing rate limiting 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.