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.
