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.

Test Endpoint

Test CAPTCHA Decider

POST/captcha/decider

Tests a CAPTCHA decider with the provided options.

JSON Params

Field	Type	Description
decider	string	The CAPTCHA decider to test
options	CAPTCHA test options object	Options for the CAPTCHA test

CAPTCHA Decider

Value	Description
hCaptchaRqdata	Tests an hCaptcha challenge with request data
SmiteRqdata	Tests a Smite challenge with request data
Recaptcha	Tests a reCAPTCHA challenge
RecaptchaEnterprise	Tests a reCAPTCHA Enterprise challenge

CAPTCHA Test Options Structure

Field	Type	Description
difficulty?	integer	The hCaptcha difficulty
should_serve_invisible?	boolean	Whether the CAPTCHA challenge should be invisible

hCaptcha Difficulty

Value	Name	Description
1	EASY	Easy
2	MODERATE	Moderate
3	DIFFICULT	Difficult
4	VERY_DIFFICULT	Very difficult

Example Request

{
  "decider": "hCaptchaRqdata",
  "options": {
    "difficulty": 3,
    "should_serve_invisible": false
  }
}

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 (used by hCaptcha)
captcha_session_id?	string	The CAPTCHA session ID (used by hCaptcha)
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 hCaptcha, the site key is dynamic and should not 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	Site Key
hcaptcha	hCaptcha	Dynamic
recaptcha ¹	reCAPTCHA	6Lef5iQTAAAAAKeIvIY-DeexoO3gj7ryl9rLMEnn
recaptcha_enterprise	reCAPTCHA Enterprise	6LeYqFcqAAAAAD6iZesmNgVulsO4PkpBdr6NVG6M

¹ 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_session_id": "0ad46c1c-98e2-45f4-a09c-ddbfde9a301c",
  "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_session_id field is present, it must be inserted into the X-Captcha-Session-Id header. 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.