import type { Metadata } from "next";
import { ERROR_CODES, ERROR_HTTP_STATUS, ERROR_MESSAGES, type ErrorCode } from "@fetcha/core";
import { CodeBlock } from "@/components/ui/code-block";
import { DocPage } from "@/components/docs/doc-page";
import { A, Code, H2, H3, Li, P, Strong, Table, TBody, Td, Th, THead, Tr, Ul } from "@/components/docs/prose";
import { Callout } from "@/components/docs/callout";
import { ParamTable } from "@/components/docs/param-table";
import { ResponseExample } from "@/components/docs/response-example";
import { CodeTabs } from "@/components/docs/code-tabs";

export const metadata: Metadata = {
  title: "Errors",
  description: "Error envelope, every error code with its HTTP status and meaning, validation details, Retry-After, request IDs and error handling in the SDKs.",
};

/** Extra guidance per code, beyond the canonical message. */
const NOTES: Record<ErrorCode, { retry: "no" | "after-fix" | "backoff" | "later"; note: string }> = {
  INVALID_API_KEY: { retry: "after-fix", note: "Missing header, malformed token, wrong prefix, revoked or expired key. Check the message for the exact reason." },
  EMAIL_NOT_VERIFIED: { retry: "after-fix", note: "Verify the organization owner's email address in the dashboard, then retry." },
  RATE_LIMITED: { retry: "backoff", note: "A sliding-window limit was hit. Honour the Retry-After header (seconds); details.retry_after_ms has the precise value." },
  CONCURRENCY_LIMIT: { retry: "backoff", note: "Too many in-flight requests for the organization. details.limit is your plan's concurrency. Queue and retry when a request finishes." },
  INVALID_REQUEST: { retry: "after-fix", note: "Schema violation, unknown field, malformed JSON, wrong Content-Type or body over 4 MB. details.issues lists each problem." },
  URL_NOT_ALLOWED: { retry: "no", note: "Non-http scheme, credentials in URL, or a host that is local, private, link-local, metadata or internal — on the initial URL or a redirect hop." },
  TARGET_TIMEOUT: { retry: "later", note: "The request budget (timeout) was exhausted across all attempts. Raise timeout within your plan cap, or retry later." },
  TARGET_BLOCKED: { retry: "later", note: "Recorded in the request log when every attempt was blocked. On the API this surfaces as a 200 with success:false and the last blocked page." },
  TARGET_UNAVAILABLE: { retry: "later", note: "DNS resolution failed, no address records, or the connection was refused on every attempt." },
  PROVIDER_UNAVAILABLE: { retry: "backoff", note: "No route is available for an auto request (all circuits open or nothing configured for the geography). Transient; retry with backoff." },
  NETWORK_UNAVAILABLE: { retry: "after-fix", note: "Explicit class not in your plan, not live yet, or without a sticky-capable route (sessions). Use auto or residential." },
  BROWSER_UNAVAILABLE: { retry: "later", note: "Browser pool disabled or unavailable. Retry later, or send the request without browser: true." },
  BROWSER_TIMEOUT: { retry: "later", note: "The page did not settle in the managed browser within the request timeout. Raise timeout, relax wait_for / wait_until, or retry." },
  RESPONSE_TOO_LARGE: { retry: "after-fix", note: "Body exceeded max_response_bytes or the 20 MB platform cap. Not retried across routes." },
  TOO_MANY_REDIRECTS: { retry: "after-fix", note: "More than max_redirects hops. Not retried across routes." },
  INSUFFICIENT_CREDITS: { retry: "after-fix", note: "Reserved for prepaid balances. Not emitted today." },
  USAGE_LIMIT_REACHED: { retry: "after-fix", note: "Monthly plan quota, project request limit, or a hard spending limit (organization or project). details tells which; see Rate limits." },
  SESSION_NOT_FOUND: { retry: "after-fix", note: "Unknown session id, or a session that belongs to another project." },
  SESSION_EXPIRED: { retry: "after-fix", note: "Session past expires_at or closed. Create a new one." },
  NOT_FOUND: { retry: "no", note: "Unknown route or resource. The message names the route." },
  FORBIDDEN: { retry: "after-fix", note: "Key lacks the required scope, project archived, or organization/account suspended." },
  INTERNAL_ERROR: { retry: "backoff", note: "Unexpected failure inside Fetcha. Retry with backoff; if it persists, send us the request_id." },
  CRAWL_NOT_FOUND: { retry: "after-fix", note: "GET/DELETE /v1/crawl/:id with an id that does not exist or belongs to another project." },
  CRAWL_LIMIT_REACHED: { retry: "later", note: "Too many crawl jobs running for the organization (5 concurrent). Wait for one to finish or cancel it." },
};

const RETRY_LABEL: Record<(typeof NOTES)[ErrorCode]["retry"], string> = {
  no: "Do not retry",
  "after-fix": "Fix, then retry",
  backoff: "Retry with backoff",
  later: "Retry later",
};

const GROUPS: Array<{ title: string; codes: ErrorCode[] }> = [
  { title: "Authentication and authorization", codes: ["INVALID_API_KEY", "EMAIL_NOT_VERIFIED", "FORBIDDEN"] },
  { title: "Request validation", codes: ["INVALID_REQUEST", "URL_NOT_ALLOWED", "NETWORK_UNAVAILABLE", "BROWSER_UNAVAILABLE", "NOT_FOUND"] },
  { title: "Limits and quotas", codes: ["RATE_LIMITED", "CONCURRENCY_LIMIT", "USAGE_LIMIT_REACHED", "INSUFFICIENT_CREDITS", "CRAWL_LIMIT_REACHED"] },
  { title: "Target and network", codes: ["TARGET_TIMEOUT", "TARGET_BLOCKED", "TARGET_UNAVAILABLE", "PROVIDER_UNAVAILABLE", "RESPONSE_TOO_LARGE", "TOO_MANY_REDIRECTS", "BROWSER_TIMEOUT"] },
  { title: "Sessions and crawls", codes: ["SESSION_NOT_FOUND", "SESSION_EXPIRED", "CRAWL_NOT_FOUND"] },
  { title: "Server", codes: ["INTERNAL_ERROR"] },
];

const JS_HANDLING = `import { Fetcha, FetchaError } from "@fetcha/sdk";

const fetcha = new Fetcha({ apiKey: process.env.FETCHA_API_KEY! });

try {
  const r = await fetcha.fetch({ url: "https://example.com", country: "CA" });
  if (!r.success) {
    // Target answered but with an error or a block page: r.status, r.metadata.attempts
    console.warn("target status", r.status, "after", r.metadata.attempts, "attempts");
  }
} catch (e) {
  if (e instanceof FetchaError) {
    // e.code, e.status (HTTP), e.message, e.requestId
    switch (e.code) {
      case "RATE_LIMITED":
      case "CONCURRENCY_LIMIT":
      case "PROVIDER_UNAVAILABLE":
        // back off and retry
        break;
      case "INVALID_REQUEST":
        // fix the request; details are in e.message
        break;
      default:
        console.error(\`\${e.code} (\${e.status}) \${e.message} — request \${e.requestId}\`);
    }
  } else {
    throw e; // network failure reaching Fetcha, JSON parse error, abort
  }
}`;

const PY_HANDLING = `from fetcha import Fetcha, FetchaError

client = Fetcha(api_key=os.environ["FETCHA_API_KEY"])

try:
    r = client.fetch("https://example.com", country="CA")
    if not r.success:
        # Target answered but with an error or a block page
        print("target status", r.status, "after", r.metadata["attempts"], "attempts")
except FetchaError as e:
    # e.code, e.status (HTTP), e.message, e.request_id
    if e.code in ("RATE_LIMITED", "CONCURRENCY_LIMIT", "PROVIDER_UNAVAILABLE"):
        ...  # back off and retry
    elif e.code == "INVALID_REQUEST":
        ...  # fix the request
    else:
        print(f"{e.code} ({e.status}) {e.message} — request {e.request_id}")`;

export default function ErrorsPage() {
  const all: ErrorCode[] = [...ERROR_CODES];
  return (
    <DocPage path="/docs/errors" eyebrow="Reliability" title="Errors" description="Fetcha uses conventional HTTP status codes and a single JSON envelope for every error. Each error carries a stable machine-readable code and the request ID." status="Stable">
      <H2>Error envelope</H2>
      <P>
        Every non-2xx response from the API has this shape. <Code>code</Code> is stable and meant for programmatic handling; <Code>message</Code> is human-readable and may change;{" "}
        <Code>details</Code> is present only for some codes.
      </P>
      <ResponseExample
        status={429}
        statusText="Too Many Requests"
        body={{ error: { code: "RATE_LIMITED", message: "Too many requests. Slow down or upgrade your plan.", request_id: "req_4e5f6g7h8i9j0k1l", details: { retry_after_ms: 640 } } }}
      />
      <ParamTable
        showDefault={false}
        rows={[
          { name: "error.code", type: "string", description: <>One of the {all.length} codes below.</> },
          { name: "error.message", type: "string", description: <>Explanation for humans. Often more specific than the default message (for example which scope is missing or which plan lacks a network).</> },
          { name: "error.request_id", type: "string | null", description: <>The request identifier, also in the <code>X-Fetcha-Request-ID</code> header.</> },
          { name: "error.details", type: "object", description: <>Optional structured context: <code>issues</code> for validation, <code>retry_after_ms</code> for rate limits, <code>limit</code> for concurrency, <code>limit</code>/<code>used</code> or <code>limit_usd</code>/<code>spent_usd</code> for quotas.</> },
        ]}
      />
      <Callout variant="info" title="A 200 is not always a success">
        <Code>/v1/fetch</Code> returns <Code>200</Code> whenever Fetcha obtained a response from the target, including a 404, a 500 or a block page. Check <Code>success</Code> and <Code>status</Code>{" "}
        in the body. Error envelopes are used only when Fetcha itself could not complete the request. See <A href="/docs/fetch#blocked-targets">Blocked targets</A>.
      </Callout>

      <H2>Error codes</H2>
      <P>The status, code and default message come straight from the API&apos;s error catalogue. The last two columns are guidance.</P>
      {GROUPS.map((g) => (
        <div key={g.title}>
          <H3>{g.title}</H3>
          <Table dense>
            <THead>
              <Tr>
                <Th>Status</Th>
                <Th>Code</Th>
                <Th>Default message and notes</Th>
                <Th>Retry</Th>
              </Tr>
            </THead>
            <TBody>
              {g.codes.map((code) => (
                <Tr key={code}>
                  <Td mono className="whitespace-nowrap">
                    {ERROR_HTTP_STATUS[code]}
                  </Td>
                  <Td mono className="whitespace-nowrap">
                    {code}
                  </Td>
                  <Td>
                    <div className="text-fg">{ERROR_MESSAGES[code]}</div>
                    <div className="mt-0.5 text-[12.5px] text-fg-muted">{NOTES[code].note}</div>
                  </Td>
                  <Td className="whitespace-nowrap text-[12.5px]">{RETRY_LABEL[NOTES[code].retry]}</Td>
                </Tr>
              ))}
            </TBody>
          </Table>
        </div>
      ))}

      <H2>Validation details</H2>
      <P>
        <Code>INVALID_REQUEST</Code> raised by schema validation includes <Code>details.issues</Code>, an array with one entry per problem. <Code>path</Code> is the dotted path of the offending field
        (empty for unknown top-level keys), <Code>message</Code> explains the constraint.
      </P>
      <ResponseExample
        status={400}
        statusText="Bad Request"
        body={{
          error: {
            code: "INVALID_REQUEST",
            message: "The request body is invalid.",
            request_id: "req_9c1d2e3f4a5b6c7d",
            details: {
              issues: [
                { path: "url", message: "String must contain at least 1 character(s)" },
                { path: "country", message: "String must contain exactly 2 character(s)" },
                { path: "max_redirects", message: "Number must be less than or equal to 20" },
                { path: "", message: "Unrecognized key(s) in object: 'proxy'" },
              ],
            },
          },
        }}
      />
      <P>Other request-level failures reuse the same code with a specific message and no <Code>issues</Code>:</P>
      <Ul>
        <Li>
          <Code>Malformed JSON body.</Code>
        </Li>
        <Li>
          <Code>Send a JSON body with Content-Type: application/json.</Code>
        </Li>
        <Li>
          <Code>Request body too large.</Code> (HTTP 413)
        </Li>
      </Ul>

      <H2>Retry-After</H2>
      <P>
        <Code>RATE_LIMITED</Code> responses include a <Code>Retry-After</Code> header in whole seconds (rounded up from <Code>details.retry_after_ms</Code>). Honour it. <Code>CONCURRENCY_LIMIT</Code>{" "}
        does not carry the header because the right moment to retry is when one of your own in-flight requests completes.
      </P>
      <CodeBlock
        lang="text"
        code={`HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-Fetcha-Request-ID: req_4e5f6g7h8i9j0k1l
Content-Type: application/json; charset=utf-8`}
      />

      <H2>Request IDs and support</H2>
      <P>
        Every response has an <Code>X-Fetcha-Request-ID</Code>; error envelopes repeat it in <Code>error.request_id</Code>. Log it alongside your own correlation id. When you contact{" "}
        <A href="mailto:support@fetcha.co">support@fetcha.co</A>, include the request id, the approximate time (UTC) and the target domain: with the id we can see every attempt, the route used, the
        outcome and the timing, without you sharing any content.
      </P>
      <P>
        <Strong>Retention:</Strong> request metadata is kept for the retention period of your plan (3 to 365 days). Response bodies are not stored, and sensitive request headers are redacted before
        logging.
      </P>

      <H2>Handling errors in the SDKs</H2>
      <P>
        Both SDKs raise a <Code>FetchaError</Code> for any non-2xx response, exposing <Code>code</Code>, <Code>status</Code>, <Code>message</Code> and the request id. A fetch that reached the target
        never throws: inspect <Code>success</Code> instead. See <A href="/docs/sdks">SDKs</A>.
      </P>
      <CodeTabs
        tabs={[
          { label: "JavaScript", lang: "typescript", code: JS_HANDLING },
          { label: "Python", lang: "python", code: PY_HANDLING },
        ]}
      />
    </DocPage>
  );
}