> ## 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.

# Errors and status codes

> Logo.dev API status codes. What 200, 202, 400, 401, 403, 404, and 429 mean for the Logo API and REST APIs, plus how missing logos and rate limits are handled.

The Logo.dev API uses standard HTTP status codes. The Logo API (`img.logo.dev`) returns an image on success; the REST APIs (`api.logo.dev`) return JSON. If a logo loads with a `200` but looks wrong (a white box, a monogram, or a blurry image), see [troubleshooting](/platform/troubleshooting).

<Note>
  **Branch on the status code, not the response body.** Error bodies are JSON with a short, human-readable message, under a `msg` key for auth, plan, and rate-limit errors, or an `err` key for bad requests and lookups. The key and the text can change, so don't parse them.
</Note>

## Status codes

| Status | Meaning                                                                                                                                                              | What to do                                                          |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `200`  | Success. The Logo API returns an image, including a generated **monogram** when no logo exists (unless you set `fallback=404`). REST APIs return JSON.               | Render the image or parse the JSON.                                 |
| `202`  | Accepted. On the REST APIs, the domain isn't indexed yet and we've started fetching it. On the Logo API, the image is served while it revalidates in the background. | Retry the REST call in a few seconds.                               |
| `400`  | Bad request: an invalid domain, parameter, or query.                                                                                                                 | Fix the request.                                                    |
| `401`  | Missing or invalid key (or a restricted referrer).                                                                                                                   | Send a valid key. See [authentication](#authentication-errors-401). |
| `403`  | Your plan doesn't include this endpoint (the Brand API needs Pro or Enterprise).                                                                                     | Upgrade, or use a different endpoint.                               |
| `404`  | Not found: the domain is known but has no data, or an image request used `fallback=404`.                                                                             | Handle the missing result.                                          |
| `429`  | You've hit your plan's request limit.                                                                                                                                | Slow down or upgrade. See [rate limits](/platform/rate-limits).     |
| `500`  | Server error.                                                                                                                                                        | Retry; contact [support](mailto:support@logo.dev) if it persists.   |

## Authentication errors (`401`)

The Logo API (`img.logo.dev`) takes a **publishable key** (`pk_…`) in the `token` query parameter. A request with no token returns `401`:

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

The REST APIs (`api.logo.dev`) take a **secret key** (`sk_…`) in the `Authorization` header. Missing it returns `401`:

```bash theme={null}
curl -i "https://api.logo.dev/search?q=stripe"
# HTTP/2 401
# {"msg":"missing api token"}
```

<Warning>
  A publishable key (`pk_`) won't authenticate the REST APIs, and a secret key (`sk_`) won't authenticate the Logo API. See [API keys](/platform/api-keys) for which key goes where.
</Warning>

## Plan errors

Some endpoints require a paid plan, and they signal it differently:

* **Describe API:** on a free account, returns `401` `{ "msg": "api not available for free accounts…" }`.
* **Brand API:** without Pro or Enterprise, returns `403` `{ "msg": "the brand API is available on Pro and Enterprise plans…" }`.

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

For the Describe and Brand APIs, a domain we haven't indexed yet returns **`202`**, not `404`. We start fetching it, and you can retry shortly:

```bash theme={null}
curl -i -H "Authorization: Bearer LOGO_DEV_SECRET_KEY" "https://api.logo.dev/describe/some-new-domain.example"
# HTTP/2 202
# {"msg":"not found, looking up"}
```

A `404` `{ "err": "not found" }` means the domain is known but has no data (or is blocked).

Each call counts as one request, including the `202` and any retries. Back off a few seconds between tries so you don't spend extra requests on repeated `202`s. See [rate limits](/platform/rate-limits).

## Missing logos

By default, an image request for a domain with no logo returns `200` with a generated monogram, so images never break in your UI. To detect and handle missing logos yourself, request `fallback=404`:

```html Default: monogram fallback (200) theme={null}
<img src="https://img.logo.dev/unknown-domain.example?token=LOGO_DEV_PUBLISHABLE_KEY" />
```

```html Opt into 404 for missing logos theme={null}
<img
  src="https://img.logo.dev/unknown-domain.example?token=LOGO_DEV_PUBLISHABLE_KEY&fallback=404"
  onerror="this.onerror=null; this.src='/images/default-logo.png';"
/>
```

See [fallback images](/logo-images/introduction#fallback-images) for the full pattern.

## Rate limits (`429`)

If you exceed your plan's request limit, the API returns `429` `{ "msg": "…" }`. This applies to **free-tier monthly limits** and the **Brand API's trial cap**. On paid plans, enforcement is soft. We email you before acting, so you generally won't hit a `429` unexpectedly. See [rate limits](/platform/rate-limits) for details.

## Response headers

Logo.dev returns no `Retry-After`, `X-RateLimit-*`, or quota headers on any endpoint. There's nothing to read for a server-suggested backoff or remaining requests, so set your own policy:

* **`202` (still indexing):** there's no fixed retry count to read from the response. [Back off a few seconds between tries](#not-found-vs-still-indexing-202), and cap it at a handful of attempts rather than looping indefinitely if a domain never resolves.
* **`429` (over limit):** see [rate limits](/platform/rate-limits) for how enforcement differs by plan.

Track remaining requests in your [dashboard](https://www.logo.dev/dashboard), the source of truth for usage.

## FAQs

<AccordionGroup>
  <Accordion title="Why am I getting a 401?">
    Your request is missing a token or using the wrong key. The Logo API needs a
    publishable key (`pk_`) as `?token=`; the REST APIs need a secret key (`sk_`)
    as `Authorization: Bearer`. Check the [API keys guide](/platform/api-keys).
  </Accordion>

  <Accordion title="Why does a brand-data request return 202 instead of the data?">
    The domain isn't in our index yet. The `202` kicks off a fetch. Retry the
    request in a few seconds and it'll resolve once indexed.
  </Accordion>

  <Accordion title="Why does an unknown company still return an image?">
    By design. Missing logos return a `200` monogram so your UI never shows a
    broken image. Add `fallback=404` if you'd rather handle missing logos
    yourself.
  </Accordion>

  <Accordion title="When do I get a 429?">
    When you exceed your plan's request limit: free-tier monthly limits, or the
    Brand API's trial cap. On paid plans, limits are soft and you're emailed
    before any enforcement. See [rate limits](/platform/rate-limits).
  </Accordion>

  <Accordion title="Should I parse the error message?">
    No. Branch on the HTTP status code. The JSON body is for debugging. The key
    (`msg` or `err`) and the wording can change.
  </Accordion>
</AccordionGroup>