Troubleshooting - Context.dev

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 three 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 domain is well-formed but the resolver couldn’t reach it (DNS failure, dead site, hostile WAF). This is effectively “no brand here,” and on /brand/retrieve it comes back as a 400, not a 404.
NOT_FOUND — no brand matched the identifier you passed. The request is not billed.

Surface an INPUT_VALIDATION_ERROR as a user-facing validation message, not a retryable failure. A WEBSITE_ACCESS_ERROR means the brand doesn’t exist or can’t be crawled, so treat it as a clean “not found.”

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 5-minute platform maximum. For reference, cold-hit latency is around 7 seconds at p50 and up to a minute at p99; cached hits return in around 250ms. Three recovery strategies, in order of preference: 1. Prefetch the domain or email. A warmed cache lands the eventual /brand/retrieve in under a second. 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');
}

Invalid Email (422)

Returned only by by_email brand lookups (POST /brand/retrieve with type: "by_email"). 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.

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.

​Bad Request (400)

​Unauthorized (401)

​Request Timeout (408)

​Invalid Email (422)

​Server Error (500)

​Missing or partial brand data (200)

​Debugging recipes

​Related resources