More expressive response codes

[VelvetToroyashi]

As it stands right now, when you screw up a request, one of two responses is bound to hit you:

• 404
• The dreaded 400

And while, under normal circumstances, this is fine, this rationale cannot be so easily translated to interactions, though, this discussion does to some extent target the API as a whole.

When it comes to interactions specically, there's one of two reasons that your request can error out.

First, I'm sure we're all aware of the 3 second window when it comes to responding to an interaction, as well as the 15 minute window for using the interaction after that.

That's fine and dandy, until you try to use an interaction outside that timeframe. You get a 404. This is fine, but I'll explain why it could be better in a bit.

There's also the issue of tryign to respond twice to an interaction. Whether it be a network issue, or simply using the trying to respond to the wrong interaction, you'll get a very cryptic 404. This is not great, because the interaction still exists, and I'd presume there's some kind of field on the interaction internally that helps Discord determine whether or not the interaction is in a valid state.

Now, if only there were a response code that could help express that. Enter 409 - Conflict .

Immediately, to anyone who's familiar with this, this makes a lot more sense, not only just on the surface, but logically as well.

Interaction ➜ Exists
State ➜ Valid

Though, a second call to /callback would imply that the response hasn't been responded to (at least, from the client pov), though the server knows it has been, which is how Discord knows to return a 404 instead of a 2xx response.

There's already an improvement, since seeing a 409 (and, after understanding what a 409 is), it's possible to deduce that the incorrect interaction was used when creating a response, without having to sift through possibly hundreds of lines of code, and potentially hours of debugging.

As per Mozilla's docs, 409 seems to be very apt for this situation, since POSTing to /callback is not an idempotent endpoint.

Moving onto expired interactions:

As I stated before, if the 3 second, or 15 minute time window is up, this is also an issue, because a 404 can be rather...vague.

Potential reasons that a 404 could occur when using an interaction are as follows:

• The interaction was never acknowledged
• Getting the original response when one was never created
• Trying to delete any ephemeral response (or followup)
• Using the wrong interaction id/token
• The interaction has expired

And plenty more.

It's not hard to see that a 404 is indicative of a lot of potential issues, and without knowing exactly where something went wrong, it isn't always easy to tell why.

This is where 410 - Gone comes into play. Once more, according to Mozilla's helpful documentation:

The HyperText Transfer Protocol (HTTP) 410 Gone client error response code indicates that access to the target resource is no longer available at the origin server and that this condition is likely to be permanent.

This is also very very apt; the interaction expired, and is no longer available, and while 404 is also an appropriate response code, for the above reason, it's simply too vague to be immediately useful, considering it's not entirely indicative of the state of request.

This resposne would refer to the ineraction itself, no matter the endpoint. Though, this may not be currently feasible given Discord's current infrastructure.

If some remnant of the interaction were cached, however, simply stating that the interaction at one point was valid, but expired, this response code would be able to be used. This could be a temporary response, too, only lasting for ~20 minutes (20 minutes as of the interaction being created, that is), after which the response code could go back to being a normal 404, as after ~20 minutes, it's doubtful that interaction would be "intentionally" used.

This would also be a very breaking change for a lot of libraries, given that 409/410 aren't very widely used, and I personaly doubt many libraries offer support for 4xx errors outside of 400, 401, 403, 404, and occasionally 405.

Also this isn't initially what I had written out, but GitHub discussions screwed me over and erased everything I typed, so hopefully this is about the same as what I had initally written down.

[muddyfish]

Personally I'd be happy with additional Discord status codes to go with the normal 404, as that wouldn't be breaking, and could have some descriptive text so we can see what actually went wrong. Of course this is possible in tangent with this discussion

[VelvetToroyashi]

I've forgot to mention it when initially making this post, but this had spontaneously come back into relevance whilst talking on Discord.

While the body of this issue has a far narrower scope than the title would imply, this actually does apply to more than just interactions, though with the direction Discord wants to steer developers, interactions are the most important, hence the initial message that spawned this discussion.

I wanted to list some examples of what can really only be described as "response code abuse/misuse".

While using HTTP 400 for anything from invalid json to the API deciding it just didn't like you is great for consistency, that's about where the good part of this stops.

There are instances where a 400 response code is returned, even for perfectly valid requests, with interactions being one that has already been extensively discussed above.

Once again, referencing Mozilla's docs , it states that:

[...] the server cannot or will not process the request due to something that is perceived to be a client error (for example, malformed request syntax [...]

With this in mind, lets review points in the API where a 400 is returned, but is not a fitting response code.

Other examples will be added to this post as they arise.

PATCH /guilds/:guild_id/members/:member_id

If you are to attempt to PATCH either mute or deaf whilst a user is not in VC, you're met with, go figure, a 400.

This is an asinine response code, especially given that this is a server-side state issue. Even a 403 makes infinitely more sense than a 400 in this context, as the request body is valid and adheres to what the API is expecting, but an error is returned because the target user is in an invalid state.

In this case, a more apt response code would be 409 - Conflict. To quote Mozilla once more:

[...] indicates a request conflict with current state of the target resource.

This makes a lot of sense for this, and likely other parameters that may throw 400 depending on their state for this endpoint.

[VelvetToroyashi]

This has been partially solved with a recent PR, but the ability to know that your interaction expired is still somewhat ambiguous.