When a rate limit violation in the API occurs, a response such as the following is received:

  "error_id": 502,
  "error_message": "Violation of backoff parameter",
  "error_name": "throttle_violation"

This is a feature request for one or both of the following:

  • Include backoff time (or time remaining) in error_message, for informative use.
  • Include backoff time (or time remaining) as a field in the response.

A well-behaved client will have received and remembered / obeyed the backoff time from the previous response. However, for a human testing the API, especially through one of the documentation test pages, sometimes this is not the case. For example, sometimes I will accidentally hit the throttle when experimenting, and realize that I did not make note of the backoff time and have no real idea when I can try again. This is followed by a few minutes of periodic retries, anxiously waiting for an unknown time period to expire.

Even well-behaved clients could benefit from this in some cases; for example if state is lost due to, say, a client application being restarted, but throttling is in effect, a more informative error message can be obtained.

I realize this is not the type of use the API was primarily designed for (humans vs. applications), but I do know that I, as a human[citation needed], have run into it multiple times. The documentation live examples in particular lend themselves to carbon-based clients.

Including the backoff time in the message rather than as a field may be a better idea as it does not provide any direct incentive for developers to have client applications poll error responses for information.

  • It can be rather long...
    – rene
    May 18, 2015 at 21:43
  • 1
    This seems counter-productive, given you're not supposed to wait for the error to back off...
    – Shog9
    Sep 15, 2016 at 0:40
  • 1
    @Shog9 Right, but the "A well-behaved..." paragraph and the one after it.
    – Jason C
    Sep 15, 2016 at 0:42
  • 2
    @Shog9 It appears that a violation of a backoff now results in a greater backoff. While the violation probably shouldn't occur (oops), the client now needs to somehow know to backoff for longer -- without any notification. I guess clients are now supposed to be omniscient...
    – hichris123
    Sep 15, 2016 at 1:02
  • 2
    Can't say I'm overly-familiar with this logic, but I'd guess it might reset the backoff if you keep trying, @hichris123 - otherwise a badly-designed client would just keep hammering away until the request went through.
    – Shog9
    Sep 15, 2016 at 1:48
  • 1
    Wow, I have just been bitten by this and it has been a known issue for seven years? Jun 30, 2022 at 3:38


You must log in to answer this question.

Browse other questions tagged .