Best Practices

If you’re building on top of Context.dev’s APIs and SDKs, this page contains some best practices to give your users a good experience.

1. Prefetch as soon as you know the domain or email

Cold Brand lookups can require a website crawl and take materially longer than warm-cache responses. Prefetching moves that work ahead of the user-facing request. It costs 0 API credits, is available to paid subscribers, and still uses the ordinary API rate limit. See Prefetch for Faster Response for the canonical pattern.

2. Cache API responses

If you need brand or classification API outputs frequently, it’s a good idea to cache them in your DB or in the browser’s localStorage. This saves your rate limit quota and API credits usage. Brand records (logos, descriptions, addresses, classifications, etc.) change very infrequently. Context.dev itself only updates a brand in cache every 3 months. Some recommended TTLs:

Data	Suggested TTL	Why
Brand response	30 days	Identity barely moves; Context.dev itself only refreshes every 3 months.
Product extractions	7 days	Catalogs change more often than identity.
Industry codes (NAICS / SIC)	Indefinite	Classification systems move on regulator timescales.

3. Set `timeoutMS` for cold hits

Warm-cache responses are generally faster. A domain Context.dev has never seen may need a live crawl, bounded by the five-minute platform timeout. If your client timeout is set to something tight like 5 seconds, you’ll cut off the exact requests that needed the most patience. So on any path that can tolerate the wait, set a generous timeout. The timeoutMS parameter lets you say it explicitly:

const { brand } = await client.brand.retrieve({
  type: "by_domain",
  domain: "example.com",
  timeoutMS: 60000, // 60s of headroom for cold hits
});

brand = client.brand.retrieve(
    type="by_domain",
    domain="example.com",
    timeout_ms=60000,
).brand

brand = client.brand.retrieve(
  body: {
    type: :by_domain,
    domain: "example.com",
    timeout_ms: 60000,
  },
).brand

// Continuing from the client setup in the Quickstart. `ctx` is your
// context.Context; `param` is github.com/context-dot-dev/context-go-sdk/packages/param.
response, err := client.Brand.Get(ctx, contextdev.BrandGetParams{
    OfByDomain: &contextdev.BrandGetParamsBodyByDomain{
        Domain: "example.com",
    },
    TimeoutMs: param.NewOpt[int64](60000),
})

$response = $client->brand->retrieve(
    type: 'by_domain',
    domain: 'example.com',
    timeoutMs: 60000, // 60s of headroom for cold hits
);
$brand = $response->brand;

timeoutMS tops out at 300,000ms (5 minutes); past that the server gives up and returns a 408. See Troubleshooting for how to handle a 408 when it does happen.

4. Run bulk jobs in the background

Some calls are inherently slow. A full-site crawl (/web/crawl) or a storefront product sweep (/brand/ai/products) walks many pages, and on a large site that can run long. Don’t block a user’s request on it. Kick the work off, return immediately, and write the results back when they land.

const response = await client.web.webCrawlMd({
  url: "https://context.dev",
  maxPages: 50,
  maxDepth: 2,
});
console.log(`${response.results.length} pages crawled`);

response = client.web.web_crawl_md(
    url="https://context.dev",
    max_pages=50,
    max_depth=2,
)
print(f"{len(response.results)} pages crawled")

response = client.web.web_crawl_md(
  url: "https://context.dev",
  max_pages: 50,
  max_depth: 2,
)
puts "#{response.results.length} pages crawled"

response, err := client.Web.WebCrawlMd(ctx, contextdev.WebWebCrawlMdParams{
    URL:      "https://context.dev",
    MaxPages: param.NewOpt[int64](50),
    MaxDepth: param.NewOpt[int64](2),
})
if err != nil {
    panic(err)
}
fmt.Printf("%d pages crawled\n", len(response.Results))

$response = $client->web->webCrawlMd(
    url: 'https://context.dev',
    maxPages: 50,
    maxDepth: 2,
);
echo count($response->results), ' pages crawled', PHP_EOL;

Wrap that call in whatever worker queue you already run (like BullMQ, Sidekiq, Cloud Tasks, or a goroutine, etc.), show the user a status field while it runs, and notify them when the result is ready. Past a few dozen pages, hand the job to the Batch API instead of running your own queue against the synchronous endpoints. Context.dev holds the queue, paces the scraping, and calls your webhookUrl when the batch settles. Batch management calls use a separate rate-limit bucket; processed work is still charged through the batch credit settlement.

5. Retry transient failures with backoff

Three error classes are worth retrying: 429 (rate limit), 408 (cold-hit timeout), and 500 (transient server error). Everything else (a 401, a 422) is a bug in the request, and retrying it just wastes calls. The retry contract (honor the Retry-After header on 429s, otherwise doubling delay, capped attempts) and copy-paste implementations in every SDK live on the Rate limits page. Use that pattern rather than rolling your own.

6. Skip free and disposable emails before you look them up

A brand-by-email lookup against gmail.com, yahoo.com, outlook.com, and the 10,000+ disposable services out there will never resolve to a company: there’s no brand behind a personal inbox. POST /brand/retrieve with type: "by_email" returns a 422 for these. You can save the round trip by filtering the obvious ones up front:

const FREE_PROVIDERS = new Set([
  "gmail.com", "yahoo.com", "hotmail.com", "outlook.com",
  "aol.com", "icloud.com", "proton.me",
]);

function shouldEnrich(email: string): boolean {
  const domain = email.split("@")[1]?.toLowerCase();
  return Boolean(domain) && !FREE_PROVIDERS.has(domain);
}

FREE_PROVIDERS = {
    "gmail.com", "yahoo.com", "hotmail.com", "outlook.com",
    "aol.com", "icloud.com", "proton.me",
}

def should_enrich(email: str) -> bool:
    parts = email.split("@")
    domain = parts[1].lower() if len(parts) == 2 else None
    return bool(domain) and domain not in FREE_PROVIDERS

require "set"

FREE_PROVIDERS = %w[
  gmail.com yahoo.com hotmail.com outlook.com aol.com icloud.com proton.me
].to_set

def should_enrich(email)
  domain = email.split("@")[1]&.downcase
  !domain.nil? && !FREE_PROVIDERS.include?(domain)
end

var freeProviders = map[string]bool{
    "gmail.com": true, "yahoo.com": true, "hotmail.com": true, "outlook.com": true,
    "aol.com": true, "icloud.com": true, "proton.me": true,
}

func shouldEnrich(email string) bool {
    parts := strings.Split(email, "@")
    if len(parts) != 2 {
        return false
    }
    return !freeProviders[strings.ToLower(parts[1])]
}

$FREE_PROVIDERS = [
    'gmail.com', 'yahoo.com', 'hotmail.com', 'outlook.com',
    'aol.com', 'icloud.com', 'proton.me',
];

function shouldEnrich(string $email): bool
{
    $parts = explode('@', $email);
    $domain = isset($parts[1]) ? strtolower($parts[1]) : null;
    return $domain !== null && !in_array($domain, $FREE_PROVIDERS, true);
}

You don’t have to maintain the full disposable-domain list yourself: POST /utility/prefetch detects 10,000+ free and disposable providers when you pass identifier.email, so calling it skips the manual guard entirely. Read how to prefetch.

7. Set up fallbacks for missing datapoints

A 200 doesn’t promise a complete record. A private company has no stock ticker, a brand-new domain may have no logo on file yet, and any optional field can come back null or empty. Fall back to a default value instead of branching your whole layout around what’s present:

const primaryColor = brand.colors[0]?.hex ?? "#000000";
const logoUrl = brand.logos[0]?.url ?? "/placeholder-logo.svg";
const description = brand.description ?? `${brand.title} (description unavailable)`;

primary_color = brand.colors[0].hex if brand.colors else "#000000"
logo_url = brand.logos[0].url if brand.logos else "/placeholder-logo.svg"
description = brand.description or f"{brand.title} (description unavailable)"

primary_color = brand.colors.first&.hex || "#000000"
logo_url = brand.logos.first&.url || "/placeholder-logo.svg"
description = brand.description || "#{brand.title} (description unavailable)"

primaryColor := "#000000"
if len(brand.Colors) > 0 {
    primaryColor = brand.Colors[0].Hex
}
logoURL := "/placeholder-logo.svg"
if len(brand.Logos) > 0 {
    logoURL = brand.Logos[0].URL
}
description := brand.Description
if description == "" {
    description = brand.Title + " (description unavailable)"
}

$primaryColor = '#000000';
if ($brand->colors) {
    $primaryColor = $brand->colors[0]->hex;
}
$logoUrl = '/placeholder-logo.svg';
if ($brand->logos) {
    $logoUrl = $brand->logos[0]->url;
}
$description = $brand->description ?? "{$brand->title} (description unavailable)";

Defensive defaults keep the page from collapsing when the API hands back a sparse record.

8. Show a real loading state on cold paths

Cold brand calls and full-site crawls take seconds, not milliseconds, long enough that a frozen screen can seem “broken.” Some recommended UI fixes:

Use skeleton boxes shaped like the content, not a generic spinner.
Echo the user’s input back optimistically while the fetch runs.
Have a graceful “we couldn’t find this one” state ready for 400 responses (NOT_FOUND or WEBSITE_ACCESS_ERROR) and sparse records.

Build it once and the wait stops feeling like a bug.

9. Keep your API key on the server

Your API key is a bearer credential: whoever holds it can spend your credits and burn your rate limit. Treat it exactly like a database password. That means it never ships in front-end code, where anyone with devtools can read it. The one exception is Logo Link, which uses a separate publicClientId credential built to be safe in the client-side browser. See Get logos from a domain.

Prefetch

Warm the cache before the user-facing call.

Rate limits

Stay under the per-minute request cap.

Tag requests

Attribute credit usage to environments, teams, or features.

Fair use

Responsible use of brand data and scraped content.

Troubleshooting

Error codes and recovery patterns.

Get Started

Give it to your Agent

What can Context.dev do

Optimizations

Integrations

1. Prefetch as soon as you know the domain or email

2. Cache API responses

3. Set `timeoutMS` for cold hits

4. Run bulk jobs in the background

5. Retry transient failures with backoff

6. Skip free and disposable emails before you look them up

7. Set up fallbacks for missing datapoints

8. Show a real loading state on cold paths

9. Keep your API key on the server

Prefetch

Rate limits

Tag requests

Fair use

Troubleshooting

​1. Prefetch as soon as you know the domain or email

​2. Cache API responses

​3. Set timeoutMS for cold hits

​4. Run bulk jobs in the background

​5. Retry transient failures with backoff

​6. Skip free and disposable emails before you look them up

​7. Set up fallbacks for missing datapoints

​8. Show a real loading state on cold paths

​9. Keep your API key on the server

​Related resources

Prefetch

Rate limits

Tag requests

Fair use

Troubleshooting

1. Prefetch as soon as you know the domain or email

2. Cache API responses

3. Set `timeoutMS` for cold hits

4. Run bulk jobs in the background

5. Retry transient failures with backoff

6. Skip free and disposable emails before you look them up

7. Set up fallbacks for missing datapoints

8. Show a real loading state on cold paths

9. Keep your API key on the server

Related resources