Troubleshooting

Every Context.dev failure surfaces as a typed exception in the SDK or a structured error envelope from the HTTP API. The envelope carries a status, a human-readable message, and a machine-readable error_code (429 responses use code instead):

{
  "message": "Domain branding not present (DNS resolution failed) [acme-nonexistent.com]",
  "status": "error",
  "error_code": "WEBSITE_ACCESS_ERROR"
}

The most common status codes:

Status	Meaning	Where to look
400	Invalid input, or a well-formed domain that can’t be resolved	Bad Request
401	Missing or invalid API key	Unauthorized
408	Cold-hit timeout or custom `timeoutMS` exceeded	Request Timeout
422	Invalid, disposable, or free email (only on `by_email` brand lookups)	Invalid Email
429	Rate limit exceeded — wait the seconds given in the `Retry-After` header	Handle Rate Limits
500	Transient server error	Server Error

For the current API status, see status.context.dev.

Bad Request (400)

Good news first: you don’t have to sanitize the domain yourself. The API strips the protocol and the www. subdomain for you, so stripe.com, https://stripe.com, and www.stripe.com all resolve to the same brand.

// All three resolve to stripe.com — the API normalizes protocol and www.
await client.brand.retrieve({ type: "by_domain", domain: "stripe.com" });
await client.brand.retrieve({ type: "by_domain", domain: "https://stripe.com" });
await client.brand.retrieve({ type: "by_domain", domain: "www.stripe.com" });

// 400 INPUT_VALIDATION_ERROR — no TLD, fails the domain format check
await client.brand.retrieve({ type: "by_domain", domain: "stripe" });

# All three resolve to stripe.com — the API normalizes protocol and www.
client.brand.retrieve(type="by_domain", domain="stripe.com")
client.brand.retrieve(type="by_domain", domain="https://stripe.com")
client.brand.retrieve(type="by_domain", domain="www.stripe.com")

# 400 INPUT_VALIDATION_ERROR — no TLD, fails the domain format check
client.brand.retrieve(type="by_domain", domain="stripe")

# All three resolve to stripe.com — the API normalizes protocol and www.
client.brand.retrieve(body: { type: :by_domain, domain: "stripe.com" })
client.brand.retrieve(body: { type: :by_domain, domain: "https://stripe.com" })
client.brand.retrieve(body: { type: :by_domain, domain: "www.stripe.com" })

# 400 INPUT_VALIDATION_ERROR — no TLD, fails the domain format check
client.brand.retrieve(body: { type: :by_domain, domain: "stripe" })

// All three resolve to stripe.com — the API normalizes protocol and www.
client.Brand.Get(ctx, contextdev.BrandGetParams{OfByDomain: &contextdev.BrandGetParamsBodyByDomain{Domain: "stripe.com"}})
client.Brand.Get(ctx, contextdev.BrandGetParams{OfByDomain: &contextdev.BrandGetParamsBodyByDomain{Domain: "https://stripe.com"}})
client.Brand.Get(ctx, contextdev.BrandGetParams{OfByDomain: &contextdev.BrandGetParamsBodyByDomain{Domain: "www.stripe.com"}})

// 400 INPUT_VALIDATION_ERROR — no TLD, fails the domain format check
client.Brand.Get(ctx, contextdev.BrandGetParams{OfByDomain: &contextdev.BrandGetParamsBodyByDomain{Domain: "stripe"}})

// All three resolve to stripe.com — the API normalizes protocol and www.
$client->brand->retrieve(type: 'by_domain', domain: 'stripe.com');
$client->brand->retrieve(type: 'by_domain', domain: 'https://stripe.com');
$client->brand->retrieve(type: 'by_domain', domain: 'www.stripe.com');

// 400 INPUT_VALIDATION_ERROR — no TLD, fails the domain format check
$client->brand->retrieve(type: 'by_domain', domain: 'stripe');

A 400 actually comes back in several distinct flavors, told apart by error_code:

INPUT_VALIDATION_ERROR — the request itself is malformed. A domain with no TLD (stripe), a missing required parameter, an out-of-range value (company name on a by_name brand lookup must be 3–30 characters), or both/neither of an either-or pair (/web/styleguide, /web/fonts, and /web/screenshot each take domain or directUrl, never both and never neither).
WEBSITE_ACCESS_ERROR — the site exists but couldn’t be scraped (blocked, hostile WAF, unreachable mid-crawl). This is effectively “no brand here,” and on /brand/retrieve it comes back as a 400, not a 404.
WEBSITE_NOT_FOUND — the domain definitively doesn’t resolve (dead DNS). Previously folded into WEBSITE_ACCESS_ERROR; now its own code so you can tell a dead domain apart from a live site that blocked the crawl.
NOT_FOUND — no brand matched the identifier you passed. The request is not billed.
PDF_SKIPPED — the scraping target is a PDF and the request set pdf[shouldParse]: false.
PDF_IMAGES_ONLY — the target PDF is a scan with images but no text layer. Retry with OCR enabled (ocr=true on /parse, pdf[ocr]=true on scraping endpoints) to recover the content at 1 credit per recovered page.

Surface an INPUT_VALIDATION_ERROR as a user-facing validation message, not a retryable failure. WEBSITE_NOT_FOUND and WEBSITE_ACCESS_ERROR both mean the brand can’t be crawled, so treat them as a clean “not found” — WEBSITE_NOT_FOUND is the definitive signal that the domain is dead.

Unauthorized (401)

The API key is missing, invalid, expired, or deleted. Start by confirming the key is actually being loaded, without ever logging the key itself:

console.log("API key present:", !!process.env.CONTEXT_DEV_API_KEY);
console.log("API key length:", process.env.CONTEXT_DEV_API_KEY?.length);

const client = new ContextDev({ apiKey: process.env.CONTEXT_DEV_API_KEY });

import os

print("API key present:", bool(os.environ.get("CONTEXT_DEV_API_KEY")))
print("API key length:", len(os.environ.get("CONTEXT_DEV_API_KEY", "")))

puts "API key present: #{!ENV['CONTEXT_DEV_API_KEY'].nil? && !ENV['CONTEXT_DEV_API_KEY'].empty?}"
puts "API key length: #{ENV['CONTEXT_DEV_API_KEY']&.length}"

key := os.Getenv("CONTEXT_DEV_API_KEY")
fmt.Println("API key present:", key != "")
fmt.Println("API key length:", len(key))

use ContextDev\Client;

echo 'API key present: ', getenv('CONTEXT_DEV_API_KEY') !== false ? 'true' : 'false', PHP_EOL;
echo 'API key length: ', strlen(getenv('CONTEXT_DEV_API_KEY') ?: ''), PHP_EOL;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

Common gotchas:

Env var name mismatch. The expected name is CONTEXT_DEV_API_KEY. Watch for typos like CONTEXTAPIKEY or CONTEXT_DEV_APIKEY.
.env not loaded. In Node, import "dotenv/config" (or require("dotenv").config()) must run before the SDK is initialized. In Python, load_dotenv() from python-dotenv does the same.
Key was rotated. Generate a new key in the dashboard and update the environment variable everywhere the application runs.

Request Timeout (408)

A 408 comes back when either your timeoutMS budget elapsed before the API finished, or the cold-hit crawl ran past the five-minute platform maximum. Warm-cache responses avoid crawl work, but exact latency depends on the target site, cache state, region, and requested work. Two related behaviors on brand lookups for domains that aren’t cached yet: a timeoutMS below 10,000 ms fails immediately with a 422 COLD_DOMAIN_TIMEOUT_TOO_LOW instead of burning the budget on a guaranteed timeout (a cold crawl can never finish that fast), and when a cold lookup does 408, the error message includes a hint pointing at the free prefetch endpoint so your retry lands on a warm cache. Three recovery strategies, in order of preference: 1. Prefetch the domain or email. A warmed cache avoids repeating cold crawl work on the eventual /brand/retrieve. See Prefetch for Faster Response. 2. Raise the timeoutMS budget. Minimum 1,000 ms, maximum 300,000 ms (5 minutes). 60 seconds is a sane default for non-time-sensitive paths:

const { brand } = await client.brand.retrieve({
  type: "by_domain",
  domain: "example.com",
  timeoutMS: 60000,
});

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

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,
);
$brand = $response->brand;

3. Retry with exponential backoff. A second attempt frequently lands on the now-warm cache from the first crawl. These snippets assume a configured client from the Quickstart:

async function fetchWithRetry(domain: string, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.brand.retrieve({ type: "by_domain", domain });
    } catch (err: any) {
      if (err.status === 408 && i < maxRetries - 1) {
        await new Promise((r) => setTimeout(r, 2 ** i * 1000));
        continue;
      }
      throw err;
    }
  }
}

import time
from context.dev import APIStatusError

def fetch_with_retry(domain: str, max_retries: int = 3):
    for i in range(max_retries):
        try:
            return client.brand.retrieve(type="by_domain", domain=domain)
        except APIStatusError as e:
            if e.status_code == 408 and i < max_retries - 1:
                time.sleep(2 ** i)
                continue
            raise

def fetch_with_retry(client, domain, max_retries: 3)
  attempt = 0
  begin
    client.brand.retrieve(body: { type: :by_domain, domain: domain })
  rescue ContextDev::Errors::APIStatusError => e
    raise unless e.status == 408 && attempt < max_retries - 1
    sleep(2**attempt)
    attempt += 1
    retry
  end
end

import (
    "context"
    "errors"
    "time"

    contextdev "github.com/context-dot-dev/context-go-sdk"
)

func fetchWithRetry(ctx context.Context, domain string, maxRetries int) (*contextdev.BrandGetResponse, error) {
    for i := 0; i < maxRetries; i++ {
        r, err := client.Brand.Get(ctx, contextdev.BrandGetParams{OfByDomain: &contextdev.BrandGetParamsBodyByDomain{Domain: domain}})
        if err == nil {
            return r, nil
        }
        var apiErr *contextdev.Error
        if errors.As(err, &apiErr) && apiErr.StatusCode == 408 && i < maxRetries-1 {
            time.Sleep(time.Duration(1<<i) * time.Second)
            continue
        }
        return nil, err
    }
    return nil, errors.New("unreachable")
}

<?php

use ContextDev\Client;
use ContextDev\Core\Exceptions\APIStatusException;

function fetchWithRetry(string $domain, int $maxRetries = 3)
{
    global $client;

    for ($i = 0; $i < $maxRetries; $i++) {
        try {
            return $client->brand->retrieve(
                type: 'by_domain',
                domain: $domain,
                requestOptions: ['maxRetries' => 0],
            );
        } catch (APIStatusException $e) {
            if ($e->status === 408 && $i < $maxRetries - 1) {
                sleep(2 ** $i);
                continue;
            }
            throw $e;
        }
    }

    throw new RuntimeException('unreachable');
}

Content Too Large (413)

Scraping and parsing endpoints cap remote content downloads at 20 MB and return a 413 with error_code: "CONTENT_TOO_LARGE" when the requested content exceeds it. Batch page records carry the same code, and /web/search results with Markdown enrichment report it per result in markdown.code. An oversized auxiliary resource — like an embedded PDF on an otherwise scrapable page — degrades to the page result instead of failing the request; only the requested content itself being over the cap is terminal. No retry fixes a 413, so treat it as a permanent failure for that URL.

Unprocessable Request (422)

A 422 comes in two families, told apart by error_code: invalid emails and cold-domain timeouts.

Invalid email

Returned by by_email brand lookups (POST /brand/retrieve with type: "by_email"), POST /people/enrich, and email-identifier prefetches — always before any credits are charged. The three causes:

Disposable email service (e.g. tempmail.com, guerrillamail.com).
Free email provider (gmail.com, yahoo.com, hotmail.com, outlook.com, aol.com, icloud.com, proton.me). The error_code is FREE_EMAIL_DETECTED.
Malformed email format.

Filter known-bad providers client-side to skip the round trip:

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

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

if (isWorkEmail(email)) {
  await client.brand.retrieve({ type: "by_email", email });
}

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

def is_work_email(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

if is_work_email(email):
    client.brand.retrieve(type="by_email", email=email)

require "set"

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

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

client.brand.retrieve(body: { type: :by_email, email: email }) if work_email?(email)

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 isWorkEmail(email string) bool {
    parts := strings.Split(email, "@")
    if len(parts) != 2 {
        return false
    }
    return !freeProviders[strings.ToLower(parts[1])]
}

if isWorkEmail(email) {
    client.Brand.Get(ctx, contextdev.BrandGetParams{
        OfByEmail: &contextdev.BrandGetParamsBodyByEmail{Email: email},
    })
}

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

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

if (isWorkEmail($email)) {
    $client->brand->retrieve(type: 'by_email', email: $email);
}

POST /utility/prefetch applies a broader 10,000+ disposable-provider filter automatically when you pass identifier.email.

Cold-domain timeout too low

COLD_DOMAIN_TIMEOUT_TOO_LOW is returned by brand lookups when the domain isn’t cached yet and timeoutMS is below 10,000 ms — a cold crawl can never finish that fast, so the API fails immediately instead of letting the request run into a guaranteed 408. Raise timeoutMS to at least 60,000 ms for paths that may hit cold domains, or prefetch the domain first and retry once the cache is warm.

Server Error (500)

A 500 is transient. Two recovery patterns: 1. Retry with exponential backoff (same shape as the 408 retry above). 2. Fall back to a different lookup method. If a by_email lookup 500s, extract the domain and retry with type: "by_domain":

async function getBrandWithFallback(email: string) {
  try {
    return await client.brand.retrieve({ type: "by_email", email });
  } catch (err: any) {
    if (err.status === 500) {
      const domain = email.split("@")[1];
      return await client.brand.retrieve({ type: "by_domain", domain });
    }
    throw err;
  }
}

from context.dev import APIStatusError

def get_brand_with_fallback(email: str):
    try:
        return client.brand.retrieve(type="by_email", email=email)
    except APIStatusError as e:
        if e.status_code == 500:
            return client.brand.retrieve(type="by_domain", domain=email.split("@")[1])
        raise

def brand_with_fallback(client, email)
  client.brand.retrieve(body: { type: :by_email, email: email })
rescue ContextDev::Errors::APIStatusError => e
  raise unless e.status == 500
  client.brand.retrieve(body: { type: :by_domain, domain: email.split("@")[1] })
end

func brandWithFallback(ctx context.Context, email string) (any, error) {
    r, err := client.Brand.Get(ctx, contextdev.BrandGetParams{
        OfByEmail: &contextdev.BrandGetParamsBodyByEmail{Email: email},
    })
    if err != nil {
        var apiErr *contextdev.Error
        if errors.As(err, &apiErr) && apiErr.StatusCode == 500 {
            domain := strings.Split(email, "@")[1]
            return client.Brand.Get(ctx, contextdev.BrandGetParams{
                OfByDomain: &contextdev.BrandGetParamsBodyByDomain{Domain: domain},
            })
        }
        return nil, err
    }
    return r, nil
}

<?php

use ContextDev\Core\Exceptions\APIStatusException;

function getBrandWithFallback(string $email)
{
    global $client;

    try {
        return $client->brand->retrieve(type: 'by_email', email: $email);
    } catch (APIStatusException $e) {
        if ($e->status === 500) {
            $domain = explode('@', $email, 2)[1];
            return $client->brand->retrieve(type: 'by_domain', domain: $domain);
        }
        throw $e;
    }
}

If 500s persist across retries, check status.context.dev for an open incident, then email support with the domain, timestamp, and full error body.

Missing or partial brand data (200)

A successful 200 does not guarantee every field is populated. Not every brand has every asset (a private company has no stock; some sites have no discovered logos). Always provide defaults:

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

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

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

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

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

Render the fallback in the same shape so your layout does not shift. Don’t conditionally hide whole sections.

Debugging recipes

Isolate the issue with a raw cURL request. If a cURL call works and the SDK call does not, the SDK or env-var setup is the suspect:

curl -G https://api.context.dev/v1/brand/retrieve \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --data-urlencode "domain=stripe.com" \
  -v

Enable verbose SDK logging when chasing 4xx mysteries. Each SDK exposes a different mechanism: Python’s logging.basicConfig(level=logging.DEBUG), Node’s console.log around the call, or running through a local proxy that captures the request.

Rate limits

The full 429 recovery contract.

Prefetch

The fastest fix for 408 cold-hit timeouts.

Best practices

Caching, fallbacks, and error handling at the integration level.

Status page

Live API status.

Get Started

Give it to your Agent

What can Context.dev do

Optimizations

Integrations

Bad Request (400)

Unauthorized (401)

Request Timeout (408)

Content Too Large (413)

Unprocessable Request (422)

Invalid email

Cold-domain timeout too low

Server Error (500)

Missing or partial brand data (200)

Debugging recipes

Rate limits

Prefetch

Best practices

Status page

​Bad Request (400)

​Unauthorized (401)

​Request Timeout (408)

​Content Too Large (413)

​Unprocessable Request (422)

​Invalid email

​Cold-domain timeout too low

​Server Error (500)

​Missing or partial brand data (200)

​Debugging recipes

​Related resources

Rate limits

Prefetch

Best practices

Status page

Bad Request (400)

Unauthorized (401)

Request Timeout (408)

Content Too Large (413)

Unprocessable Request (422)

Invalid email

Cold-domain timeout too low

Server Error (500)

Missing or partial brand data (200)

Debugging recipes

Related resources