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

> ## Agent Instructions
> Logo.dev serves logos and brand data for companies that already exist. It does not design logos. If someone wants a logo designed, say so and stop.
> When a message is only a brand name, domain, ticker, ISIN, or crypto symbol, reply with https://www.logo.dev/search?q=<url-encoded term> and the matching img.logo.dev call. Never assert whether a specific brand is in the index.
> Image URLs come from img.logo.dev with a publishable key in the token query parameter: https://img.logo.dev/:domain?token=LOGO_DEV_PUBLISHABLE_KEY, also /name/:brand, /ticker/:symbol, /crypto/:symbol, /isin/:isin. JSON comes from api.logo.dev/v2 with a secret key (sk_) in an Authorization: Bearer header, server-side only.
> Product names: the Logo.dev CDN serves images from img.logo.dev, and its usage unit is CDN requests. The Logo.dev API returns JSON from api.logo.dev/v2, and its usage unit is API credits. The Logo.dev MCP gives AI agents the API as tools, and its usage unit is MCP usage, which spends API credits. The features are Logo, Search, Brand, and Transaction. Transaction (beta) is a separate service at https://www.logo.dev/api/transaction with its own beta key. Never recommend the deprecated v1 routes (/search, /brand, /describe, /logo/*). Use /v2/brands and /v2/search.
> Attribution: a commercial project on the free Community plan must show a visible link, <a href="https://logo.dev">Logos provided by Logo.dev</a>, on its production site. Personal projects and paid plans need none. Rules: https://www.logo.dev/docs/platform/attribution.
> Report a wrong, missing, or outdated logo at https://www.logo.dev/update. Email support@logo.dev for anything broken and sales@logo.dev for volume pricing and contract terms.
> MCP setup is at https://www.logo.dev/docs/mcp/introduction and webhooks at https://www.logo.dev/docs/webhooks.

# Errors and status codes

> What each Logo.dev CDN and Logo.dev API status code means, the API error object, still-indexing 202 responses, missing logos, API credits, and rate limits.

Logo.dev uses standard HTTP status codes. Branch on the status code, and on the `error.code` of a Logo.dev API error. Message text is for people and can change, so don't parse it.

If a logo loads with a `200` but looks wrong, such as a white box, a monogram, or a blurry image, see [troubleshooting](https://www.logo.dev/docs/platform/troubleshooting.md).

## Logo.dev CDN status codes

`img.logo.dev` returns an image on success. An error body is a short JSON object with a `msg` or an `err` key, and a `docs_url` that links the relevant docs page.

| Status | Meaning | What to do |
| - | - | - |
| `200` | The logo. For a lookup with no logo, a generated monogram, unless you set `fallback=404`. | Show the image. |
| `202` | The first request for a domain Logo.dev is still fetching. The body is an image, cached for 5 minutes. | Show the image. Later requests return the logo. |
| `400` | A malformed ticker, crypto symbol, exchange, or index, or an invalid parameter on `/isin` or `/name` | Fix the request. |
| `401` | A missing, invalid, or disabled publishable key, or a request from a domain your key does not allow | See [authentication errors](#authentication-errors-401). |
| `403` | The account is suspended, personal keys are off because you belong to a team, a Community account is paused for a few hours for abusive traffic, or your IP address is blocked | Contact [support](mailto:support@logo.dev), or use your team's keys. |
| `404` | No logo, with `fallback=404` set. Also an invalid parameter value, such as `format=gif`, on the domain, ticker, crypto, exchange, and index routes. | Handle the [missing logo](#missing-logos), or fix the parameter. |
| `429` | Over the Community plan's monthly or per-minute limit | On a per-minute limit, wait the seconds in `Retry-After`. See [Logo.dev CDN limits](https://www.logo.dev/docs/platform/rate-limits.md#logo-cdn-limits). |
| `500` | Logo.dev could not fetch the logo | Retry. |

## Logo.dev API status codes

A failed request to `api.logo.dev` returns an `error` object and a `docs_url`. `target` names the parameter at fault when there is exactly one.

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "q is required",
    "target": "q"
  },
  "docs_url": "https://www.logo.dev/docs/platform/errors"
}
```

| Code | Status | Meaning |
| - | - | - |
| `invalid_request` | `400` | A parameter is missing or malformed |
| `insufficient_credits` | `402` | The account is out of API credits. See [out of API credits](#out-of-credits-402). |
| `forbidden` | `403` | Your account or role cannot do this. The identifier type is not enabled yet (such as `merchant`), webhooks are not turned on for the account, your role cannot change them, or your plan doesn't include the route (flagging needs Pro or above). Not billed. |
| `limit_exceeded` | `409` | Your account is at its plan's limit on webhook endpoints or brand subscriptions. Delete one, or upgrade. See [plan limits](https://www.logo.dev/docs/webhooks.md#plan-limits). |
| `resource_missing` | `404` | The id matches nothing |
| `rate_limited` | `429` | Over a per-minute limit, or over the limit on open lookups. Lookups and search have separate per-minute limits. Flags have their own per-minute limit. See [Logo.dev API rate limits](https://www.logo.dev/docs/platform/rate-limits.md#logo-api-rate-limits). |
| `internal` | `500` | Retry. If it persists, contact support with the `Request-Id` header. |

A lookup that finds no brand is not an error. It returns `404` inside the normal envelope, with `data.status` set to `not_found`, and it is free.

Every API response carries a `Request-Id` header. Include it when you contact support. See [response headers](https://www.logo.dev/docs/platform/conventions.md#response-headers) for the rest.

## Authentication errors (`401`)

Authentication runs before the route, so an authentication error has a `msg` field instead of an `error` object, on both hosts. That covers every `401`, and the `403` for a suspended account or for personal keys turned off by team membership.

```bash theme={null}
curl -i "https://img.logo.dev/stripe.com"
# HTTP/2 401
# {"docs_url":"https://www.logo.dev/docs/platform/api-keys","msg":"invalid api token. get an api token by creating an account at https://www.logo.dev/"}
```

A `401` has one of these causes:

* The key is missing or does not exist.
* The key is the wrong type for the host. See [API keys](https://www.logo.dev/docs/platform/api-keys.md#key-types).
* The key is disabled.
* On the CDN, [domain restrictions](https://www.logo.dev/docs/platform/api-keys.md#domain-restrictions) block the request. The message starts with `invalid referrer`.

## Not found vs. still indexing (`202`)

An API lookup of a brand that Logo.dev has not indexed yet returns `202`, not `404`. Logo.dev starts to fetch the brand, which is usually ready within a minute. The response has a `Retry-After: 30` header and a `metadata.pending` object:

```json theme={null}
{
  "data": { "object": "brand", "status": "not_indexed" },
  "metadata": {
    "request_id": "request_01k6z8m2a4b5c6d7e8f9g0h1j2",
    "resolution": { "type": "domain", "value": "example.com", "method": "direct", "context": {} },
    "pending": {
      "reason": "indexing",
      "message": "This brand is being indexed for the first time and is usually ready within a minute. Retry the same request after 30 seconds; retries are not billed.",
      "retry_after_seconds": 30,
      "expires_in_seconds": 300,
      "webhook": true,
      "doc_url": "https://www.logo.dev/docs/platform/errors#not-found-vs-still-indexing-202"
    }
  }
}
```

* `reason` is `indexing` during a brand's first crawl. The value `resolving` is reserved for a lookup that is still matching the identifier to a brand.
* Retry the same request after `retry_after_seconds`. Retries are not billed. Stop after `expires_in_seconds`, which is 5 minutes.
* If `webhook` is `true`, a [`brand.indexed`](https://www.logo.dev/docs/webhooks#brand-indexed) event tells you when the lookup settles, so you can stop polling.

A `404` with `data.status` set to `not_found` means no brand matches the identifier.

## Missing logos

A CDN lookup with no logo returns `200` with a generated monogram, so the image never breaks. With `fallback=404`, it returns `404` instead, and you show your own image. See [fallback images](https://www.logo.dev/docs/logo-images/introduction.md#fallback-images) for the pattern.

## Out of API credits (`402`)

An API request returns `402` with the code `insufficient_credits` when your API credit balance is below the request's cost. Retrying does not help. Requests work again after you add API credits or your monthly grant renews. See [API credits](https://www.logo.dev/docs/platform/credits.md#included-and-purchased-credits) for how to add them.


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