Skip to main content
When Brandfetch refuses a request, the 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 as error, next to a human-readable message and a docs link to the matching table:
The Logo API is usually loaded by an <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

  1. A 429 without x-bf-error is a throughput limit. Slow down and retry after the window. A 429 with quota_exceeded means the monthly quota or allowance is used up, and retrying will not help. See limits and billing.
  2. 500 and 503 are on our side. Retry with backoff. Nothing in your request needs to change.
  3. A 404 on a brand lookup means we looked. The code says whether looking again can help. crawl_queued means retry in a minute or two, while domain_unresolvable means 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 answered 402 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.

See your errors

Logo API and Brand Search API responses for your own traffic are listed under Usage History in the developer dashboard, filtered by status class.