Brave Search API 422 is ambiguous: read error.code, not the status

Brave Search API 422 is ambiguous: read error.code, not the status

TL;DR

Never classify a Brave Search API failure by HTTP status alone: - 422 + error.code SUBSCRIPTIONTOKENINVALID: the key is wrong or revoked. - 422 + error.code VALIDATION: a parameter is wrong (e.g. an invalid country code).

Use this when you run into the situation in the title.

When not to use this skill: unrelated tasks. It covers only the procedure above.

Compatibility

The steps above apply to the commands named in them. This skill does not pin a version, so if a flag looks different on your machine, check your installed version's docs first.

Details

Rotate the key. 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.