Clarification on Status Code When reCAPTCHA v3 Quota Is Exceeded

[Hiroaki]

Hello. 

I have a question regarding the behavior of reCAPTCHA v3 when the number of verification requests exceeds the quota.

According to the documentation below, it is stated that when API usage exceeds the specified quota limit, new requests should return an HTTP error with a status code of 429 (Resource Exhausted):

https://cloud.google.com/recaptcha/quotas?hl=en#quota_limit

Show More

"When your API usage quotas exceed the specified quotas limit, any new request returns an HTTP error with a Resource Exhausted (429) status code.

For V2, an end-user-visible error message is shown similar to the following message: This site is exceeding reCAPTCHA quota."

However, in practice, it appears that the response status code is still 200, even when the quota is exceeded. In such cases, the success field in the response is set to false, and the error-codes field contains a message like the following:

Show More

Over Enterprise free quota. Please ensure your project has an active billing account: https://cloud.google.com/recaptcha-enterprise/billing-information

Reference: https://developers.google.com/recaptcha/docs/v3?hl=en#site_verify_response

We would like to implement specific handling for when the quota is exceeded. However, since the error message string may change due to specification updates, we are unsure how to reliably detect this condition.

Could you please advise how we should programmatically determine that the quota has been exceeded, given that the status code is not 429 as described in the documentation?

Thank you in advance for your assistance.

[tessa_hudson]

Hello,

The behavior in the documentation is for the CreateAssessment endpoint which returns a 429 when quota is exceeded.

The SiteVerify endpoint (/recaptcha/api/siteverify) behaves as you described when quota is exceeded. It will return a 200 status with an error code in the response.

[Hiroaki]

Hello, Thank you for your response.

Just to confirm, the behavior described in the following documentation refers specifically to the CreateAssessment API, correct?

https://cloud.google.com/recaptcha/quotas?hl=en#quota_limit

I found it a bit unclear which API the documentation was referring to at first, so it might be helpful to explicitly mention that it applies to CreateAssessment.

In my case, I’m using the siteverify endpoint, and I would like to detect when the quota has been exceeded.
Is checking whether the error message includes `Over Enterprise free quota` the only reliable way to detect this condition?

Thank you in advance for your help.

[tessa_hudson]

---

Just to confirm, the behavior described in the following documentation refers specifically to the CreateAssessment API, correct?

https://cloud.google.com/recaptcha/quotas?hl=en#quota_limit

I found it a bit unclear which API the documentation was referring to at first, so it might be helpful to explicitly mention that it applies to CreateAssessment.

Yes, this is specifically for CreateAssessment. Sorry for the confusion. I will discuss potential clarification with doc owners.

---

In my case, I’m using the siteverify endpoint, and I would like to detect when the quota has been exceeded.
Is checking whether the error message includes `Over Enterprise free quota` the only reliable way to detect this condition?

---

Yes, siteverify will consistently return this error message in the error-codes field when quota has been exceeded.

[Hiroaki]

Thank you for your response.

I will proceed with the approach of detecting quota exceedance based on the error message in the error-codes field.

Also, would it be possible to consider adding information about the error code returned when the quota is exceeded to the following `siteverify` documentation?

https://developers.google.com/recaptcha/docs/verify