> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brandfetch.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Brandfetch returns real company logos, brand data, and brand context. It does not design, generate, or edit logos.
> To show a logo in a user interface, use the Logo API as an image URL in an <img> tag, such as https://cdn.brandfetch.io/domain/{domain}?c={CLIENT_ID}. The client ID is public and belongs in frontend code. Never download, proxy, re-host, or optimize these images on a server, because requests that look programmatic are redirected with automated_traffic. In Next.js, this means next/image needs a custom loader or the unoptimized prop.
> To turn a company name that a user types into a domain, use the Brand Search API with the same client ID, and keep only the domain the user picks.
> For colors, fonts, downloadable logo files, and company data as JSON, call the Brand API from a server with the header Authorization: Bearer {API_KEY}, reading the key from an environment variable and never exposing it to the browser. Prefer typed routes such as /v2/brands/domain/{domain} and /v2/brands/ticker/{ticker} over the auto-detect route /v2/brands/{identifier}.
> Use the Brand Context API for a written summary of what a company does, who it sells to, and how it sounds, and the Transaction API to identify the merchant behind a card or bank transaction label.
> When a request fails, branch on the x-bf-error header code rather than on the status code or the message text. Every code, and what to do about it, is listed at https://docs.brandfetch.com/concepts/errors.
> Requests for brandfetch.com are free on the Brand API and Brand Context API, so use that domain in tests and examples.
> Brand API responses can be cached for up to 30 days, while Logo API images must be hotlinked rather than stored and Brand Search results must not be stored at all. See https://docs.brandfetch.com/concepts/caching.
> If the user has no credentials yet, https://brandfetch.com/auth.md explains how they get a client ID and an API key. An agent without an account can pay $0.10 per Brand API, Brand Context API, or Transaction API request with x402 or MPP, as described at https://docs.brandfetch.com/agents/pay-per-request.

# Errors

> How Brandfetch reports a refused request, and where each error code is documented

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:

```json theme={null}
{
  "message": "Not Found",
  "error": "domain_unresolvable",
  "docs": "https://docs.brandfetch.com/brand-api/overview#errors"
}
```

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](https://docs.brandfetch.com/concepts/limits-and-billing.md).
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.

| Product | Codes | Table |
| - | - | - |
| Brand API | `identifier_invalid`, `route_invalid`, `lookup_kind_invalid`, `email_invalid`, `url_invalid`, `identifier_ambiguous`, `authorization_required`, `payment_required`, `api_key_invalid`, `no_api_credits`, `paid_plan_required`, `auth_unavailable`, `quota_exceeded`, `brand_not_found`, `identifier_unknown`, `brand_removed`, `brand_withheld_nsfw`, `domain_invalid`, `domain_unresolvable`, `domain_redirected`, `site_unavailable`, `crawl_queued`, `internal_error`, `temporarily_unavailable` | [Brand API errors](https://docs.brandfetch.com/brand-api/overview.md#errors) |
| Transaction API | `body_invalid`, `transaction_unmatched`, plus the Brand API credential and brand codes | [Brand API errors](https://docs.brandfetch.com/brand-api/overview.md#errors) |
| Brand Context API | `generation_in_progress`, `temporarily_unavailable` | [Brand Context API errors](https://docs.brandfetch.com/brand-context-api/overview.md#errors) |
| Brand Search API | `quota_exceeded`, `rate_limited`, `client_id_invalid_signature`, `client_id_required`, `client_id_expired`, `temporarily_unavailable` | [Brand Search API errors](https://docs.brandfetch.com/brand-search-api/overview.md#errors) |
| Logo API | `client_id_invalid_signature`, `client_id_disabled`, `region_unavailable`, `client_id_expired`, `quota_exceeded`, `rate_limited`, `client_id_required`, `user_agent_required`, `hotlink_blocked`, `automated_traffic` | [Logo API errors](https://docs.brandfetch.com/logo-api/overview.md#errors) |

## 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](https://docs.brandfetch.com/agents/pay-per-request.md) 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](https://developers.brandfetch.com), filtered by status class.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.