x-bf-error response header usually names the exact reason with a stable code such as quota_exceeded or domain_unresolvable. Several reasons share a status code but each has its own x-bf-error, so branch on that code whenever it is present rather than on the status or the message text. When the header is absent, fall back to the status and the product’s error table, which is how the Brand Context API tells you that a site blocks automated requests (422) or that no context could be generated (404).
Response shape
JSON APIs repeat the code in the body aserror, next to a human-readable message and a docs link to the matching table:
<img> tag, where your page never sees the body, so read the header in your browser’s network panel instead.
Three rules that cover most cases
- A
429withoutx-bf-erroris a throughput limit. Slow down and retry after the window. A429withquota_exceededmeans the monthly quota or allowance is used up, and retrying will not help. See limits and billing. 500and503are on our side. Retry with backoff. Nothing in your request needs to change.- A
404on a brand lookup means we looked. The code says whether looking again can help.crawl_queuedmeans retry in a minute or two, whiledomain_unresolvablemeans the domain does not exist.
Codes by product
Each product page has the full table, with what happened and what to do.Payment errors
A request with no credential is answered402 Payment Required. Its body is the payment protocol’s own, so only the x-bf-error: payment_required header names the refusal. Pay per request explains how to pay it, or send an API key instead.