Codestin Search App

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.

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 or invalid credential	Fix server configuration.
`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`	Request exceeded its time budget	Raise the budget, move work off the critical path, or retry with a limit.
`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`	Current rate window exhausted	Honor `Retry-After` and use bounded backoff.
`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.
`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.

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 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`	Key or organization access to the operation
`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

timeoutMS is the request’s hard time budget. 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 timeoutMS 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

Production

Troubleshooting

Start with the evidence

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

​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

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