CAPTCHA Handling

Discord employs CAPTCHAs to prevent abuse when performing high-risk actions such as logging in, accepting invites, and sending friend requests. Some endpoints will always return a CAPTCHA, while others will only return one if the user is sending suspicious requests or has performed a large number of high-risk actions in a short period of time.

Identifying CAPTCHAs

When a request is challenged, the endpoint will return a 400 bad request with a response body looking similar to a legacy error response:

CAPTCHA Response Structure

Field	Type	Description
captcha_key	array[string]	The CAPTCHA service errors
captcha_service	string	The CAPTCHA service to use
captcha_sitekey ¹	?string	The CAPTCHA site key
captcha_rqdata? ²	string	Custom data to be sent on challenge requests (used by hCaptcha Enterprise)
captcha_rqtoken?	string	The CAPTCHA challenge request token (used by hCaptcha Enterprise)
should_serve_invisible?	boolean	Whether the CAPTCHA challenge should be invisible

¹ For reCAPTCHA, this field is null as the site key is always 6Lef5iQTAAAAAKeIvIY-DeexoO3gj7ryl9rLMEnn. For hCaptcha, the site key is now dynamic and should no longer be hard-coded.

² If this field is present, it must be used in the challenge request or the challenge will fail.

CAPTCHA Service

Value	Description
hcaptcha	hCaptcha
recaptcha ¹	reCAPTCHA
recaptcha_enterprise ¹	reCAPTCHA Enterprise

¹ reCAPTCHA is not currently used by Discord, but may be used again in the future.

Example CAPTCHA Response

{
  "captcha_key": ["invalid-input-response", "response-already-used-error"],
  "captcha_sitekey": "f5561ba9-8f1e-40ca-9b5b-a0b3f719ef34",
  "captcha_service": "hcaptcha"
}

On certain endpoints that have not previously returned CAPTCHAs, the captcha_key array may contain an error message to display to older clients that made incorrect assumptions about CAPTCHA availability. For example:

{
  "captcha_key": ["You need to update your app to join this server."],
  "captcha_sitekey": "b2b02ab5-7dae-4d6f-830e-7b55634c888b",
  "captcha_service": "hcaptcha",
  "captcha_rqdata": "32ODySYSI08RDvfcOKNA25zs8hGNVeD75qXuvAiuXnhgGV1tEqL/M6jHj9NJhuN3843/3Xb0y4qL9X85UhNWMLmXgvqDdUEJSKv1NlqrGqmBhi8qC2W4nKMzYeEFpGPMTqqC12Gp8BCZ+SPn9Dw0g3c=SMTWOoJOQKEpSoHZ",
  "captcha_rqtoken": "Im4rRTZXUWRTNFhyWTFpZUpEbVM3YVl1bFd6dU0zNUt0VkhzMEVoTHJNcC9wSmVqT29kS1FJVFpYYVgrT0RNd254YjFVQUE9PXVnalltRDZtNEFKOW85VXMi.ZfYH3g.beZ-lIsxWGcY5J0VUzE_odCbh24"
}

To correctly identify CAPTCHAs, clients should check for a 400 bad request status code and the presence of the captcha_key field and not rely on the specific errors within the array.

Solving CAPTCHAs

When a CAPTCHA is returned, the client must display a CAPTCHA challenge to the user. How this is done depends on the CAPTCHA service used. See the hCaptcha and reCAPTCHA documentation for more information.

After the user has solved the CAPTCHA, the request should be retried with the CAPTCHA solution inserted into the X-Captcha-Key header. Additionally, if the captcha_rqtoken field is present, it must be inserted into the X-Captcha-Rqtoken header.

If the solution is not accepted, the endpoint will return a 400 bad request with a response body similar to the original CAPTCHA response. Note that an otherwise valid solution may be rejected if the solution's bot score is too high or the captcha_rqdata/captcha_rqtoken fields are not properly handled.