The three outcomes
A request for a brand ends in one of three ways:
A
crawl_queued response means the crawl keeps going in the background. Retry in a minute or two, and if the brand could be collected, the retry returns it.
The Brand Context API reports the same situation differently. While a context is still being generated, it answers 503 with x-bf-error: generation_in_progress and a Retry-After header that says how many seconds to wait. That response is not charged.
Prefetch with HEAD
When you know which brand you will need a few steps from now, such as right after a user signs up, ask for it in advance with a HEAD request on the Brand API route:
200 means the brand is ready, and 202 means a crawl has been queued so the GET you make later is fast. Prefetching needs a paid plan. See the prefetch reference for every status code.
Skip the crawl with cachedOnly
When latency matters more than coverage, add cachedOnly=true. The API then answers from its store and never crawls:
200 as usual. A brand that is not indexed returns 204 No Content, which has no body and does not count towards your quota. Check the status before you parse the response.
cachedOnly works on every Brand API GET route and on the Brand Context API.