Getting Started

Error Codes

When a request fails, SupaCrawlX returns the same predictable JSON every time — a machine-readable code, a human-readable message, and the request ID — so you can branch on failures with confidence.

Error response shape

4xx / 5xx

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "requestId": "req_abc123xyz"
  }
}

Error code reference

HTTP	Code	Description
400	`BAD_REQUEST`	Missing or malformed request parameters
401	`UNAUTHORIZED`	Missing or invalid API key
402	`INSUFFICIENT_CREDITS`	Not enough credits to complete the request
403	`PLAN_REQUIRED`	Feature not available on your current plan
404	`NOT_FOUND`	Resource not found
206	`TRANSCRIPT_NOT_AVAILABLE`	No transcript exists for this video
422	`UNSUPPORTED_URL`	URL format is not supported
422	`VIDEO_UNAVAILABLE`	Video is private, deleted, or geo-blocked
429	`RATE_LIMIT_EXCEEDED`	Too many requests — slow down
500	`INTERNAL_ERROR`	Unexpected server error — retry with backoff

Handling errors in code

from supacrawlx import Client, APIError

client = Client("YOUR_API_KEY")

try:
    result = client.transcript("https://www.youtube.com/...")
    print(result.text)
except APIError as e:
    print(f"Error {e.status_code}: {e.code} — {e.message}")