Troubleshooting

Context.dev errors include an HTTP status, a human-readable message, and usually a stable error_code. Use the status to identify the broad category and the code to decide what the application should do.

Start with the evidence

Before changing retry logic:

Record the operation, timestamp, status, error_code, and response headers.
Confirm that CONTEXT_DEV_API_KEY exists without printing its value.
Reproduce the request with raw HTTPS so SDK serialization is not part of the test.
Compare the request with the operation’s current API-reference page.
Check the status page when unrelated operations fail at the same time.

Choose an operation, then compare cURL with your SDK. The SDK examples disable automatic retries so you can inspect the first response. Keep diagnostic output private and redact it before sharing.

Brand request
Web request

curl -i https://api.context.dev/v1/brand/retrieve \
  --request POST \
  --header "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "type": "by_domain", "domain": "stripe.com" }'

import ContextDev from "context.dev";

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

try {
  const { data, response } = await client.brand.retrieve({
    type: "by_domain",
    domain: "stripe.com",
  }).withResponse();
  console.log(response.status, Object.fromEntries(response.headers), data);
} catch (error) {
  if (!(error instanceof ContextDev.APIError)) throw error;
  console.log(error.status, error.headers && Object.fromEntries(error.headers), error.error);
}

import os
from context.dev import ContextDev, APIStatusError

client = ContextDev(
    api_key=os.environ["CONTEXT_DEV_API_KEY"],
    max_retries=0,
)

try:
    response = client.brand.with_raw_response.retrieve(
        type="by_domain",
        domain="stripe.com",
    )
    print(response.status_code, dict(response.headers), response.parse())
except APIStatusError as error:
    print(error.status_code, dict(error.response.headers), error.body)

require "cgi/core"
require "context_dev"

client = ContextDev::Client.new(
  api_key: ENV.fetch("CONTEXT_DEV_API_KEY"),
  max_retries: 0,
)

begin
  response = client.brand.retrieve(
    body: { type: "by_domain", domain: "stripe.com" },
  )
  puts response.inspect
rescue ContextDev::Errors::APIStatusError => error
  puts error.status, error.headers.inspect, error.body.inspect
end

# Successful calls return the parsed model in Ruby 2.14.0.
# Use the cURL tab to inspect successful response headers.

package main

import (
	"context"
	"fmt"
	"net/http"
	"os"

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

func main() {
	client := contextdev.NewClient(
		option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
		option.WithMaxRetries(0),
	)
	var raw *http.Response
	data, err := client.Brand.Get(context.Background(), contextdev.BrandGetParams{
		OfByDomain: &contextdev.BrandGetParamsBodyByDomain{
			Domain: "stripe.com",
		},
	}, option.WithResponseInto(&raw))
	if raw != nil {
		fmt.Println(raw.StatusCode, raw.Header)
	}
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Printf("%+v\n", data)
}

<?php
require __DIR__.'/vendor/autoload.php';

use ContextDev\Client;
use ContextDev\Core\Exceptions\APIException;

$client = new Client(
    apiKey: getenv('CONTEXT_DEV_API_KEY'),
    requestOptions: ['maxRetries' => 0],
);

try {
    // The 2.14.0 Brand helper cannot represent this request correctly.
    // The SDK's public request method keeps authentication and request options.
    $response = $client->request(
        method: 'post',
        path: 'brand/retrieve',
        body: ['type' => 'by_domain', 'domain' => 'stripe.com'],
    );
    $data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
    var_dump($response->getStatusCode(), $response->getHeaders(), $data);
} catch (APIException $error) {
    var_dump($error->status, $error->response?->getHeaders(), $error->body);
}

curl -i --get https://api.context.dev/v1/web/scrape/markdown \
  --header "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --data-urlencode "url=https://example.com"

import ContextDev from "context.dev";

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

try {
  const { data, response } = await client.web.webScrapeMd({
    url: "https://example.com",
  }).withResponse();
  console.log(response.status, Object.fromEntries(response.headers), data);
} catch (error) {
  if (!(error instanceof ContextDev.APIError)) throw error;
  console.log(error.status, error.headers && Object.fromEntries(error.headers), error.error);
}

import os
from context.dev import ContextDev, APIStatusError

client = ContextDev(
    api_key=os.environ["CONTEXT_DEV_API_KEY"],
    max_retries=0,
)

try:
    response = client.web.with_raw_response.web_scrape_md(
        url="https://example.com",
    )
    print(response.status_code, dict(response.headers), response.parse())
except APIStatusError as error:
    print(error.status_code, dict(error.response.headers), error.body)

require "cgi/core"
require "context_dev"

client = ContextDev::Client.new(
  api_key: ENV.fetch("CONTEXT_DEV_API_KEY"),
  max_retries: 0,
)

begin
  response = client.web.web_scrape_md(
    url: "https://example.com",
  )
  puts response.inspect
rescue ContextDev::Errors::APIStatusError => error
  puts error.status, error.headers.inspect, error.body.inspect
end

# Successful calls return the parsed model in Ruby 2.14.0.
# Use the cURL tab to inspect successful response headers.

package main

import (
	"context"
	"fmt"
	"net/http"
	"os"

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

func main() {
	client := contextdev.NewClient(
		option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
		option.WithMaxRetries(0),
	)
	var raw *http.Response
	data, err := client.Web.WebScrapeMd(context.Background(), contextdev.WebWebScrapeMdParams{
		URL: "https://example.com",
	}, option.WithResponseInto(&raw))
	if raw != nil {
		fmt.Println(raw.StatusCode, raw.Header)
	}
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Printf("%+v\n", data)
}

<?php
require __DIR__.'/vendor/autoload.php';

use ContextDev\Client;
use ContextDev\Core\Exceptions\APIException;

$client = new Client(
    apiKey: getenv('CONTEXT_DEV_API_KEY'),
    requestOptions: ['maxRetries' => 0],
);

try {
    $response = $client->web->raw->webScrapeMd(
        params: ['url' => 'https://example.com'],
    );
    $data = $response->parse();
    var_dump($response->getStatusCode(), $response->getHeaders(), $data);
} catch (APIException $error) {
    var_dump($error->status, $error->response?->getHeaders(), $error->body);
}

If raw HTTPS succeeds and the SDK call fails, inspect the installed package version, generated method signature, serialized path, and request body.

Trace a request through logs

Save the original call’s request_id or X-Request-Id. Use that ID with Retrieve Request Log to inspect retained inputs, response content, status, and credit usage. A restricted key needs logs:read; log endpoints cost zero credits and use a separate rate limit. Replace the example UUID below with the ID of the call you are investigating. The returned data.request_id identifies that original call; the outer request_id identifies the log-retrieval request itself.

These examples use the SDKs’ low-level request methods to send the current API contract, including fields not yet exposed by the 2.14.0 typed helpers. Authentication, retries, and error handling still come from the SDK. See SDK compatibility.

curl --get https://api.context.dev/v1/logs/00000000-0000-4000-8000-000000000000 \
  --header "Authorization: Bearer $CONTEXT_DEV_API_KEY"

import ContextDev from "context.dev";

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

const response = await client.get<{ data: { request_id: string; status_code: number; error_code: string | null } }>("/logs/00000000-0000-4000-8000-000000000000", {
  query: {}
});

console.log(response.data.request_id, response.data.status_code, response.data.error_code);

import os
from context.dev import ContextDev

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])

response = client.get(
    "/logs/00000000-0000-4000-8000-000000000000",
    cast_to=dict[str, object],
    options={"params": {}},
)

entry = response["data"]
print(entry["request_id"], entry["status_code"], entry["error_code"])

require "cgi/core"
require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))

response = client.request(
  method: :get,
  path: "logs/00000000-0000-4000-8000-000000000000",
  query: {}
)

entry = response.fetch(:data)
puts entry[:request_id], entry[:status_code], entry[:error_code]

package main

import (
	"context"
	"fmt"
	"os"

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

func main() {
	client := contextdev.NewClient(option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")))
	var response struct {
		Data struct {
			RequestID  string  `json:"request_id"`
			StatusCode int     `json:"status_code"`
			ErrorCode  *string `json:"error_code"`
		} `json:"data"`
	}
	err := client.Get(context.Background(), "/logs/00000000-0000-4000-8000-000000000000", nil, &response)
	if err != nil {
		panic(err)
	}
	fmt.Println(response.Data.RequestID, response.Data.StatusCode, response.Data.ErrorCode)
}

<?php
require __DIR__.'/vendor/autoload.php';

use ContextDev\Client;

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

$raw = $client->request(
    method: 'get',
    path: 'logs/00000000-0000-4000-8000-000000000000',
    query: [],
);

$response = json_decode((string) $raw->getBody(), true, flags: JSON_THROW_ON_ERROR);
$entry = $response['data'];
echo $entry['request_id'], ' ', $entry['status_code'], PHP_EOL;
var_dump($entry['error_code']);

Keep diagnostic output to metadata you need; retained inputs and responses can contain application data even after credential redaction. Recognized credential fields, nested header entries, and credentials in URLs are redacted on ingestion and when older logs are read. ZDR requests retain operational metadata without request/response content. To find related calls, List Request Logs accepts key_id, path, status_code, error_code, tags, and time filters. The dashboard’s per-key usage links apply key filters to both charts and logs. to defaults to now and from to 24 hours before to. Explicit ranges longer than 30 days are accepted; a larger query window does not extend the retention of available records.

Decide by status

Status	Category	Default response
`400`	Invalid input, inaccessible target, blocked target, or operation-specific no-match	Inspect `error_code`; most cases should not be retried unchanged.
`401`	Missing, invalid, or disabled access	Inspect `error_code`; fix credentials or check account/key state.
`403`	Permission, plan, disabled key, or usage problem	Inspect `error_code`; change authorization or usage state.
`404`	Target or resource not found	Treat as an expected empty result where the operation defines it.
`408`	Deadline expired without an acceptable result	Raise the budget, select partial mode where supported, or move work off the critical path.
`413`	Content exceeds the supported size	Narrow or change the source; do not retry unchanged.
`415`	Unsupported content type	Choose a supported parsing flow.
`422`	Semantically unprocessable request	Change the email class, timeout, or other request semantics.
`429`	Account rate limit or authentication protection	Honor `Retry-After`; account metadata can be absent.
`500`	Internal service failure	Retry with bounded backoff, then use a product fallback.

The same error_code can appear under different statuses on different operations. Build logic around the combination documented for the endpoint you call.

Input and website errors

`error_code`	Meaning	Recovery
`INPUT_VALIDATION_ERROR`	A required field is missing, a value is malformed, or incompatible options were combined.	Fix the request. Do not retry the same body.
`TIMEOUT_TOO_SHORT_FOR_WAIT`	The deadline cannot accommodate `waitForMs` plus the 10,000 ms load/capture margin.	Increase `timeoutOpts.milliseconds` or lower `waitForMs`.
`NOT_FOUND`	The resolver or operation did not find a matching entity.	Keep the original input and return an unmatched state.
`WEBSITE_NOT_FOUND`	The target URL or domain was identified as not found.	Correct the URL or stop processing that record.
`WEBSITE_ACCESS_ERROR`	The site could not be fetched or used for the operation.	Try later only when the target may recover; keep a fallback.
`WEBSITE_BLOCKED`	The returned page was a challenge, CAPTCHA, or login shell rather than the requested content.	Retry later or with an appropriate country route; do not promise eventual access.

WEBSITE_BLOCKED on the scrape endpoints is not billed. For any error response that includes key_metadata, use credits_consumed as the operation-specific billing evidence. Direct HTTP and PDF fetching requires public HTTP(S) destinations and checks redirects, DNS/IP safety, and TLS certificates. Correct an invalid certificate or private destination instead of retrying the same inaccessible source. Challenge pages are not usable content; scraping tries available fallback routes and returns WEBSITE_BLOCKED when access remains blocked.

Authentication and access

For 401 UNAUTHORIZED:

console.log("Context.dev key present:", Boolean(process.env.CONTEXT_DEV_API_KEY));

Common causes are a misspelled variable, an unloaded .env file, a rotated key, or initializing the client before environment loading runs. For 401 DISABLED, check the key and organization state in the dashboard. Contact [email protected] if access remains disabled; do not keep retrying. For 403, inspect the code:

`error_code`	Check
`USAGE_EXCEEDED`	Credit balance or plan allowance in the dashboard
`PAID_PLAN_REQUIRED`	Whether the feature requires a paid plan
`INSUFFICIENT_PERMISSIONS`	Inspect `required_permission` and the key’s scope grants; denials are unbilled.
`DISABLED`	Key or organization state
`FORBIDDEN`	The operation’s reference page for a more specific prerequisite

Repeating a 401 or 403 request does not repair credentials or permissions.

Handle timeouts

timeoutOpts.milliseconds sets the request deadline. behavior: "fail" is the default; supported operations can instead return usable incomplete data with behavior: "return-partial". Preserve partial: true or finalDOMState: "still-loading". If no usable result exists, the request fails without a charge. See Timeouts and partial results, including the product-catalog migration. Cache misses and operations that crawl or run models can take longer than cache hits. For a Brand request on a cold domain, a timeout below 10 seconds can return 422 COLD_DOMAIN_TIMEOUT_TOO_LOW before retrieval starts. Raise the budget or prefetch the identifier before it is needed. For 408 REQUEST_TIMEOUT:

Move optional work to a background job.
Increase timeoutOpts.milliseconds only when the product can wait longer.
Use a smaller crawl or extraction scope.
Retry with a small total attempt count.
Do not hide a multi-minute retry chain inside a user request.

Handle email rejection

Invalid email

Brand-by-email, people enrichment, and email prefetch operations can return:

FREE_EMAIL_DETECTED
DISPOSABLE_EMAIL_DETECTED
INPUT_VALIDATION_ERROR for malformed input

Treat these as validation outcomes. Ask for a work email, allow manual company entry, or skip enrichment. Do not retry the same address.

Content limits

`error_code`	Meaning	Recovery
`CONTENT_TOO_LARGE`	Requested remote content exceeds the 20 MB limit.	Use a smaller file or narrower source.
`UNSUPPORTED_CONTENT`	The target content type is unsupported for that endpoint.	Use document parsing or another supported source.
`PDF_SKIPPED`	The request disabled PDF parsing for a PDF target.	Enable parsing or intentionally skip the record.
`PDF_IMAGES_ONLY`	The PDF has no usable text layer.	Enable OCR for the supported PDF flow.

Changing a timeout or retry delay does not fix a size or media-type failure.

Handle ZDR errors

`error_code`	Meaning
`ZDR_NOT_ENABLED`	The organization has not been enabled for Zero Data Retention.
`ZDR_NOT_SUPPORTED`	The selected operation does not support ZDR.

Do not silently retry without zdr; that changes the data-handling promise. Either stop the request or follow an explicitly approved non-ZDR path. See Zero Data Retention.

Batch and monitor errors

These codes describe resource state rather than a transient transport problem:

BATCH_LIMIT_EXCEEDED: wait for active work to finish or reduce concurrency.
BATCH_NOT_COMPLETED: keep polling with backoff; results are not ready.
BATCH_NOT_CANCELLABLE: the batch has reached a state that cannot be cancelled.
IDEMPOTENCY_KEY_CONFLICT: the key was reused with a different body; use the original body or a new key.
MONITOR_LIMIT_EXCEEDED: reduce monitor count or change the plan.
MONITOR_PAUSED: resume the monitor before running it.
MONITOR_NO_WEBHOOK: add a webhook before rotating its secret.

Use the Batch guide or Monitor guide for the relevant state machine.

Diagnose SDK mismatches

Check these when cURL works:

The installed package version matches the documentation you followed.
Parameter casing matches the language, such as maxAgeMs in TypeScript and max_age_ms in Python.
The SDK sends the documented HTTP method and path.
A generated union accepts only fields from one request variant.
An SDK’s automatic retry policy is not masking the first response.

The old unversioned Go SDK v1.5.0 and the PHP SDK v2.14.0 have known Brand request compatibility issues. Check the versions and examples in the SDK guide. Use raw HTTP when your installed client cannot represent the current POST /brand/retrieve request.

Handle partial success

A 200 can still contain:

Missing optional Brand fields.
An empty Markdown result because an include selector matched nothing.
Page-level crawl failures inside an otherwise successful crawl response.
Skipped or blocked pages in structured extraction metadata.
Low-confidence classification candidates.

Validate the product outcome, not only the status code. Preserve the user’s input and render a stable fallback when optional enrichment is absent.

Contact support

If the problem persists, contact [email protected] with:

Operation path and HTTP method.
UTC timestamp and region.
Status, error_code, response headers, and response body.
A redacted request body or query.
SDK language and exact package version, if applicable.
Whether the equivalent cURL request succeeded.

Remove API keys, private page content, cookies, authorization headers, and personal data before sending the report.

Next steps

Rate limits

Read limit headers and recover from 429 responses.

Production checklist

Add retries, fallback states, and request observability.

API stability

Separate API contract changes from SDK compatibility issues.

Get started

Web data

Brand data

Automation

Account and billing

Production

Start with the evidence

Trace a request through logs

Decide by status

Input and website errors

Authentication and access

Handle timeouts

Handle email rejection

Invalid email

Content limits

Handle ZDR errors

Batch and monitor errors

Diagnose SDK mismatches

Handle partial success

Contact support

Next steps

Rate limits

Production checklist

API stability

​Start with the evidence

​Trace a request through logs

​Decide by status

​Input and website errors

​Authentication and access

​Handle timeouts

​Handle email rejection

​Invalid email

​Content limits

​Handle ZDR errors

​Batch and monitor errors

​Diagnose SDK mismatches

​Handle partial success

​Contact support

​Next steps

Rate limits

Production checklist

API stability

Start with the evidence

Trace a request through logs

Decide by status

Input and website errors

Authentication and access

Handle timeouts

Handle email rejection

Invalid email

Content limits

Handle ZDR errors

Batch and monitor errors

Diagnose SDK mismatches

Handle partial success

Contact support

Next steps