Discord error 4012: Invalid API version

The v query parameter on your gateway URL (for example wss://gateway.discord.gg/?v=10&encoding=json) names a gateway version Discord does not serve. Very old versions have been discontinued; current clients should use v10. Connecting with a removed version, a version that does not exist, or a malformed value results in 4012, and Discord marks it not reconnectable because the same URL will keep failing.

This is the WebSocket twin of REST error 50041. You will see it with very old library releases, with a hand-built gateway URL, or with configuration that overrides the version. Some libraries allow a ws.version or gateway_version option; a typo there is enough. Gateway proxies that rewrite the URL are another source.

// WebSocket close frame
code: 4012
reason: "Invalid API version"

Keep the library current and let it own the gateway URL. Do not pin gateway versions in application config; if you must, keep the value in one place with a link to the API versioning table.

Pin the library version in your lockfile and subscribe to its release notes; gateway version deprecations are announced well in advance, and a routine dependency update is all it takes to stay current. If you run a custom client, add the gateway version to your startup log so a mismatch is obvious in the first line of output.

The gateway version parameter and its REST counterpart usually live in the same config block, so audit both when either error appears; the REST variant is 50041. Connection parameters are listed with the gateway limits on the Discord limits page.