Errors

All errors from the Bytekit API follow a consistent envelope shape so you can handle them programmatically.

Error response shape

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 2 seconds.",
    "details": {}
  }
}

Field	Description
`error.code`	Machine-readable string identifier
`error.message`	Human-readable explanation
`error.details`	Optional object with additional context (e.g. which field failed validation)

Common error codes

HTTP status	Code	Meaning
`400`	`invalid_request`	Malformed JSON, missing required field, or failed validation
`401`	`unauthorized`	Missing or invalid API key
`402`	`quota_exceeded`	Account has exceeded its plan quota
`403`	`forbidden`	Key is valid but lacks permission for this action
`429`	`rate_limited`	Too many requests; back off and retry
`502`	`internal_error`	The upstream fetch or browser render failed

Webhook URLs Must Use HTTPS

All webhook URLs submitted to the Bytekit API must use HTTPS. Plain HTTP URLs (e.g. http://example.com/webhook) are rejected with a 422 Unprocessable Entity error.

Why HTTPS only? Webhook payloads may contain sensitive data (API keys, session tokens, scrape results). HTTPS encryption protects this data in transit.

Request with an invalid webhook URL:

{
  "webhook_url": "http://example.com/webhook"
}

Response (HTTP 422):

{
  "error": "validation_error",
  "message": "webhook_url must use https:// scheme"
}

Working example:

{
  "webhook_url": "https://example.com/webhook"
}

This applies to all endpoints that accept a webhook_url parameter: /v1/scrape (async), /v1/scrape/bulk, /v1/fetch/bulk, /v1/bulk, /v1/monitors, and /v1/sitemap.

Retry guidance

Not all errors are retryable. Use this table to decide:

Code	Retry?	Guidance
`invalid_request`	No	Fix the request before retrying
`unauthorized`	No	Check your API key
`quota_exceeded`	No	Upgrade your plan or wait for quota reset
`forbidden`	No	You do not have access to this resource
`rate_limited`	Yes	Exponential backoff; honour the `Retry-After` header
`internal_error`	Yes	Exponential backoff; most resolve on retry

For retriable errors, start with a 1-second delay and double on each subsequent failure, up to a maximum of 60 seconds. Respect the Retry-After header value when it is present on 429 responses.

Example: handling errors in curl

response=$(curl -s -w "\n%{http_code}" -X POST https://api.bytekit.com/v1/scrape \
  -H "Authorization: Bearer sk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}')

http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | head -1)

if [ "$http_code" -ge 400 ]; then
  echo "Error $http_code: $body"
fi

Next steps

Rate Limits — quota model, concurrency slots, rate limit headers
Scraping — when 502 internal_error occurs and how fallback works
API Reference — per-endpoint error codes