Error codes

These are the fair/* codes currently used by the FairCrawl API or first-party SDK layers.

Code	Where it appears	Meaning
fair/validation-error	API + SDKs	invalid request body, query params, or schema
fair/not-found	API	requested freshness source or resource does not exist
fair/service-unavailable	API	upstream worker, browser, or external service failed
fair/internal-error	API	unexpected internal failure inside the orchestration path
fair/rate-limited	platform-wide problem type	canonical rate-limit code used across Fair
fair/request-timeout	SDKs	client-side timeout waiting for a response
fair/network-error	SDKs	network or transport failure before a valid API response arrived

Error payload shape

{
  "type": "https://api.faircompany.ai/errors/fair/validation-error",
  "title": "Validation Error",
  "status": 400,
  "code": "fair/validation-error",
  "detail": "proxy_country must be a 2-letter uppercase ISO code"
}

TypeScript handling

import { FairCrawl, FairCrawlError } from "faircrawl";

try {
  await fc.scrape({ url: "https://example.com", proxy_country: "usa" });
} catch (error) {
  if (error instanceof FairCrawlError) {
    console.log(error.code);
    console.log(error.detail);
  }
}

Python handling

from faircrawl import FairCrawl
from faircrawl.errors import FairCrawlError

try:
    FairCrawl().scrape("https://example.com", proxy_country="usa")
except FairCrawlError as error:
    print(error.code)
    print(error.message)