Pre-Emptive Client Backoff

[mfortini]

Client should backoff nearing saturation

We used the Limit and Remain values in one of our client applications that was migrated from a legacy SOAP service to our REST based API in order to ensure we never get a 429 response (this is because the legacy code could not gracefully retry requests without major refactoring).

When we get to 80% of quota (20% Remain) we start respecting the value in the Reset header. In section 7 you touched on a concept ‘A client SHOULD NOT exceed the "quota-units" expressed in "RateLimit-Remaining" before the "time-window" expressed in "RateLimit-Reset".’

Would it be an idea to document that clients should be coded to pre-emptively back-off when nearing “saturation”?

We don't want to mandate a strict behavior on client, but we can surely add this sentence as an example behavior.

Note

Would one want to have to option to provide a saturation hint in the Limit definition ?

The current spec allows Limit comments, so you can already do it. The spec allows to address this use-case transparently, by artificially lowering the values provided in the fields.

[ioggstream]

We should probably integrate and remove FAQ 8 since it's already in the spec.

[unleashed]

Would one want to have to option to provide a saturation hint in the Limit definition ?

This is something I quickly commented on #34 (comment) but the alternative of dynamically modifying the values as the rate saturates is fairly reasonable, so those informational parameters might as well be part of an extension document.