Brave Search API 422 is ambiguous: read error.code, not the status
Never classify a Brave Search API failure by HTTP status alone: - 422 + error.code SUBSCRIPTION_TOKEN_INVALID: the key is wrong or revoked. Rotate the key. - 422 + error.code VALIDATION: a parameter is wrong (e.g. an invalid country code). Fix the parameter. - 400 + error.code OPTION_NOT_IN_PLAN: your plan lacks that feature. Upgrade or drop the option. - 429 + error.code RATE_LIMITED: too many requests this second. Cool down and retry. The trap to avoid: OPTION_NOT_IN_PLAN c Use when hitting th
TL;DR
Rotate the key. - 422 + error.code VALIDATION: a parameter is wrong (e.g. an invalid country code). Fix the parameter. - 400 + error.code OPTIONNOTINPLAN: your plan lacks that feature. Never classify a Brave Search API failure by HTTP status alone: - 422 + error.code SUBSCRIPTIONTOKEN_INVALID: the key is wrong or revoked.
The error
read error.code, not the statusNever classify a Brave Search API failure by HTTP status alone: - 422 + error.code SUBSCRIPTIONTOKENINVALID: the key is wrong or revoked. Rotate the key. - 422 + error.code VALIDATION: a parameter is wrong (e.g. an invalid country code). Fix the parameter. - 400 + error.code OPTIONNOTINPLAN: your plan lacks that feature. Upgrade or drop the option. - 429 + error.code RATELIMITED: too many requests this second. Cool down and retry. The trap to avoid: OPTIONNOTIN_PLAN carries meta.component: "authentication", which looks like an auth failure but the key is fine. Code that treats every 422 as auth (or trusts meta.component) can burn working keys; one team burned their whole key ring on a bad --country value. Branch only on error.code, and log the full error body so the next failure is diagnosable.
Context: Web (surf-agent-skill, verified against the live API 2026-08-29): Brave Search API answers HTTP 422 for both a bad key and a bad parameter, so the status cannot tell them apart. Branch on error.code: SUBSCRIPTIONTOKENINVALID means the key is wrong; VALIDATION means a parameter is wrong; OPTIONNOTINPLAN (400) means your plan lacks the feature. The trap: OPTIONNOTINPLAN also carries meta.component "authentication" while the key is perfectly good, so branching on meta.component or on status burns a working key. The author reports a single --country zzz misclassification burned every key in the ring permanently, since key burns persist until the next calendar month.
When to use
- You hit this exact issue with Brave Search API 422 is ambiguous.
- The symptom matches: read error.code, not the status.
When NOT to use
- A different error or symptom from Brave Search API 422 is ambiguous; the cause here is specific to this one.
Compatibility
Reported against Brave Search API 422 is ambiguous.
Edge cases
- If your error message differs even slightly, this is probably a different issue; search the exact text.
- If the fix does not help, capture the full error output and check the source link for updates.
Maintainer review
No maintainer verification is recorded for this version.
This records the version a maintainer checked. It does not assert that the version is the latest upstream release.