specify rate-limit algorithm exceptions

[switchupcb]

There is an issue that needs to be addressed by Discord regarding per-resource rate limits.

TL:DR Optimal Implementations require a consistent specification; which currently is confirmed to be inconsistent due to unstated exceptions.

Context

The context of this entire thread can be found from the following issues.

• add rate limit algorithm clarification for global rate limits #5144
• clarify per-resource rate limit algorithm #5557
• add Per Resource Rate Limits switchupcb/disgo#22 (comment)
• add Per Resource Rate Limits switchupcb/disgo#22 (comment)

A summary is that Discord Rate Limits Documentation is missing information which prevents API Wrappers from providing optimal API Consumers. Discord punishes the end user for not adhering to rate limits such that the end user must implement them. Yet the specification is confirmed to have "mistakes and exceptions". Mistakes happen. That is fine. Then there are the exceptions...

Symptom

switchupcb/disgo#22 showcases the implications of having exceptions in relation to a modern optimal rate limit implementation. In summary, a secure working rate limit implementation is possible with the current rate limit specification, but can't be optimal in a few cases due to "exceptions".

As an example, top-level resources are defined as channels (channel_id), guilds (guild_id), and webhooks (webhook_id or webhook_id + webhook_token) and routes that use them at the start of the request path are specified as per-resource rate-limit algorithm routes accordingly. An invite is not a per-resource route according to the specification, but confirmed by @devsnek to be one anyways. The implications of these exceptions (incorrectly specified resources) can result in memory overhead to Bot Users (costing them money) or — in prevention of those issues — result in inefficient bots.

Solution

In order to solve this problem, Bot Users Need Exceptions to the Rate Limit Algorithm Specification Specified. If the documentation states that per-resource routes only apply to "xyz" (channel, guilds, webhooks), but then also applies the per-resource route "r" (invites) this is inconsistent. State that r is an exception in the documentation for the end-user.

[switchupcb]

This discussion may be relevant to the following users.

Context:
#5144: @erkinalp @splatterxl @Bluenix2 @Zoddo @LordOfPolls
#5557: @TAG-Epic @SuperSajuuk @AlmostSuspense @mbialecka @IanMitchell @night
Rate Limit Editors (#4694): @shaydewael @devsnek @advaith1

[SuperSajuuk]

I really have no idea why you pinged me for, i literally don’t care about this topic whatsoever. I liked one comment from Night, because i agreed with him about how you were being rude to the maintainers [who are all discord employees] and telling them what they can and can’t do. Mass mentioning random users for no reason is unnecessary and i would ask you not to @ me into this topic again, thank you,

[switchupcb]

There's a difference between being straightforward and rude.

I liked one comment from Night
— @SuperSajuuk

As you stated, you were involved in that issue — on an answer that provided information about rate limits — and I pinged accordingly. In a similar manner to other users, you could have simply closed the ping. Certain users are happy for being pinged. Others (such as @LordOfPolls) are using these threads to implement rate limit consumers, and should NOT be burdened by future bugs that occur due to using outdated information. As night said, "please refrain from such accusatory comments, as these tend to not be productive for anyone involved".

In the following sentences, I capitalize and bold NOT. This is done NOT to be rude, but so that statements are NOT misinterpreted. If you consider this rude, it's not personal.

With that being said, I will provide my perspective of this situation. I stated (in #5557) that I — as a contributor to the documentation — do NOT believe that the issue that @yonilerner — a Discord member, but NOT a contributor to the documentation — closed should have been. This statement was made specifically with regards to a request by @yonilerner which would prevent any issues regarding rate-limit clarification from being made.

From #5144

Based on the need for this discussion (#5605), my notion was correct. Regardless, I stated it in a manner that was taken the wrong way. For that, I apologize. However, I also believe that one should NOT take it personally when others point out issues with the API on the API Documentation Forum. If I didn't tell him to leave the #5557 thread open, API Consumers would NOT have received the necessary information for optimal rate limit implementations. This is significant because suboptimal rate limit implementations cost users money. Such that these statements are NOT a matter of being rude, but making the point clear.

Ironically, this exchange (between supersajuuk and I) has only occurred because he participated in an issue that he wasn't following.

In any case, non-straightforward communication — in the specification — is how we end up with issues such as these. This is why I believe that rate limit algorithm exceptions should be specified.

[switchupcb]

Alternatively, if exceptions will never be specified, feel free to state that. However, this implies that per-resource rate limits were never meant to be adhered to.

[IanMitchell]

Alternatively, if exceptions will never be specified, feel free to state that.

This is indeed the case. I would also ask that you do not mass ping people, and if someone requests you do not ping them to absolutely not reply with a ping. Please be respectful of their wishes.

I am going to lock this thread to prevent further pings.