Reference

Errors

The error envelope and every error code the API returns, with what causes it and what to do next.

The error envelope

Every response that is not a 2xx has the same JSON body, on every endpoint. code is stable and safe to branch on; message is a sentence for a developer and may change; docs links to the entry for the code on this page. details, when present, holds machine-readable facts for that code: the credit balance for insufficient_credits, the seconds to wait for rate_limited and quota_exceeded.

402 Payment Required

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits: this request needs 1 and the balance is 0. Add credits at https://brandidentityapi.com/billing (subscribe, or buy a top-up pack). Search and the logo CDN keep working.",
    "docs": "https://brandidentityapi.com/docs/errors#insufficient_credits",
    "details": {
      "balance": 0,
      "required": 1,
      "billing_url": "https://brandidentityapi.com/billing"
    }
  }
}

Lookups that fail never cost a credit. Successful responses carry X-Credits-Remaining, so you can see a low balance coming. The logo CDN answers with images and plain-text errors instead, so an img tag never receives JSON.

All codes

Code	Status	Costs a credit
unauthorized	401	No
forbidden	403	No
invalid_request	400	No
not_found	404	No
insufficient_credits	402	No
rate_limited	429	No
quota_exceeded	429	No
upstream_failed	502	No
internal_error	500	No
invalid_domain	400	No
domain_not_found	404	No
fetch_failed	502	No
fetch_blocked	422	No
timeout	504	No
no_brand_data	404	No

unauthorized

HTTP 401

The request had no API key, or the key is mistyped, revoked or deleted.

What to do: Send Authorization: Bearer lh_sk_.... Check the key on the API keys page; create a new one if it was revoked.

forbidden

HTTP 403

The key is valid but may not do this: a publishable key called an endpoint that needs a secret key, or the account is suspended.

What to do: Call brand lookups, batch and /v1/me from your server with a secret key. If your account is suspended, write to us.

invalid_request

HTTP 400

A parameter or the request body is not valid: a missing q, a limit out of range, a body that is not JSON, or a batch larger than your plan allows.

What to do: The message names the field and the problem. Fix that field and send the request again.

not_found

HTTP 404

No endpoint answers at this path and method.

What to do: Check the path against the endpoint list. Brand lookups live under /v1/brands/.

insufficient_credits

HTTP 402

Your account has no credits left for this request. A brand lookup costs one credit when it finds a brand with a logo; a batch reserves one per domain. The balance can also be below zero after a refunded payment's credits had already been spent.

What to do: Add credits on the billing page: subscribe to a plan, or buy a top-up pack if you already have one. Credits never expire. error.details carries the balance, what the request required and the billing_url; in a batch, the domains the credits did not cover answer this code one by one. Do not retry on a timer: nothing changes until credits are added. Search, the logo CDN and /v1/me keep working, and nothing is ever charged automatically.

rate_limited

HTTP 429

Too many requests in the current minute for your plan.

What to do: Wait the number of seconds in Retry-After, then retry. Spread bursts out, or use the batch endpoint.

quota_exceeded

HTTP 429

Your plan's searches for this calendar month (UTC) are used up. Only search answers this code; a logo request past its monthly allowance is served as if it had no key.

What to do: Upgrade on the billing page: a higher plan's allowance applies at once. Otherwise the month starts over on the 1st (UTC). Retry-After and error.details.retry_after give the seconds until then, and details.limit your plan's monthly allowance. Do not retry on a short timer. Brand lookups keep working. See monthly limits.

upstream_failed

HTTP 502

A service we depend on failed while answering your request.

What to do: Retry after a short pause. Nothing was counted.

internal_error

HTTP 500

Something failed on our side. A 503 with this code means usage metering was briefly unavailable, so the request did not run.

What to do: Retry after Retry-After seconds, or a few seconds if there is none. If it keeps happening, send us the X-Request-Id. Nothing was counted.

invalid_domain

HTTP 400

The identifier has no public domain in it: an IP address, localhost, a private suffix such as .local, or text that is not a domain, URL or email address.

What to do: Send a domain such as stripe.com. URLs must be URL-encoded in the path. Nothing was counted.

domain_not_found

HTTP 404

No site answers at that domain.

What to do: Check the spelling. If the company is new, try again once its site is live. Nothing was counted.

fetch_failed

HTTP 502

The brand's site could not be fetched: it was down, broke the connection or sent an error.

What to do: Retry later; the site may be having a bad day. Nothing was counted.

fetch_blocked

HTTP 422

The site refused our crawler, or its domain resolves to an address we never fetch, such as a private network.

What to do: Retrying will not help. If it is your own site, allow the BrandIdentityBot user agent. Nothing was counted.

timeout

HTTP 504

The live crawl of a new domain ran out of time, usually because the site is very slow.

What to do: Retry in a minute or two. Nothing was counted.

no_brand_data

HTTP 404

The site answered, but there was nothing to build a brand from, such as a parked domain or an empty page.

What to do: Try the company's main marketing domain. Nothing was counted.