Errors and status codes

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.

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.

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.
`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.
`500`	Server error.	Retry; contact support 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:

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:

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

A publishable key (pk_) won’t authenticate the REST APIs, and a secret key (sk_) won’t authenticate the Logo API. See API keys for which key goes where.

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:

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 202s. See 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:

Default: monogram fallback (200)

<img src="https://img.logo.dev/unknown-domain.example?token=LOGO_DEV_PUBLISHABLE_KEY" />

Opt into 404 for missing logos

<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 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 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, and cap it at a handful of attempts rather than looping indefinitely if a domain never resolves.
429 (over limit): see rate limits for how enforcement differs by plan.

Track remaining requests in your dashboard, the source of truth for usage.

FAQs

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.

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.

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.

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.

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.

​Status codes

​Authentication errors (401)

​Plan errors

​Not found vs. still indexing (202)

​Missing logos

​Rate limits (429)

​Response headers

​FAQs

Status codes

Authentication errors (`401`)

Plan errors

Not found vs. still indexing (`202`)

Missing logos

Rate limits (`429`)

Response headers

FAQs