@talonic/docs 0.20.0 → 0.20.2

package/dist/content.js

@@ -34,7 +34,9 @@ var API_NAV_SECTIONS = [
     { id: "introduction", label: "Introduction" },
     { id: "authentication", label: "Authentication" },
     { id: "base-url", label: "Base URL" },
-    { id: "quick-start", label: "Quick Start" }
+    { id: "quick-start", label: "Quick Start" },
+    { id: "pagination", label: "Pagination" },
+    { id: "idempotency", label: "Idempotency" }
   ] },
   { id: "extract", label: "Extract", children: [
     { id: "post-extract", label: "POST /v1/extract" },
@@ -4426,11 +4428,24 @@ var sections17 = [
     parentSlug: "overview",
     title: "Authentication",
     seoTitle: "API Authentication \u2014 Talonic Docs",
-    description: "Learn how to authenticate with the Talonic API using Bearer tokens and API keys with the tlnc_ prefix, scoped to a source.",
+    description: "Learn how to authenticate with the Talonic API using Bearer tokens and API keys with the tlnc_ prefix. Keys carry scopes (extract, read, write) that control access.",
     content: [
-      { type: "paragraph", text: "All API requests require a Bearer token in the `Authorization` header. API keys are scoped to a source and carry the `tlnc_` prefix. You can create and manage keys from **Settings → API Keys** in the dashboard." },
+      { type: "paragraph", text: "All API requests require a Bearer token in the `Authorization` header. API keys carry the `tlnc_` prefix and can be scoped to a source. Create and manage keys from **Settings \u2192 API Keys** in the dashboard." },
       { type: "code", language: "bash", title: "Authorization header", code: `curl https://api.talonic.com/v1/documents \\
-  -H "Authorization: Bearer tlnc_sk_live_7f3a...x9k2"` },
+  -H "Authorization: Bearer $TALONIC_API_KEY"` },
+      { type: "heading", level: 2, id: "api-key-scopes", text: "API Key Scopes" },
+      { type: "paragraph", text: "Each API key carries one or more scopes that determine which operations it can perform. New keys default to all three scopes." },
+      {
+        type: "param-table",
+        title: "Available scopes",
+        params: [
+          { name: "extract", type: "scope", description: "Submit documents for extraction (`POST /v1/extract`, `POST /v1/documents/:id/re-extract`)." },
+          { name: "read", type: "scope", description: "Read operations \u2014 list and retrieve documents, extractions, schemas, jobs, sources, and other resources." },
+          { name: "write", type: "scope", description: "Write operations \u2014 create, update, and delete schemas, sources, jobs, delivery bindings, and other resources." },
+          { name: "billing", type: "scope", description: "Billing operations \u2014 trigger credit top-ups (`POST /v1/billing/topup`). Not included by default; add explicitly when creating the key." }
+        ]
+      },
+      { type: "paragraph", text: "New keys default to `extract`, `read`, and `write`. The `billing` scope must be added explicitly. If a request requires a scope your key does not carry, the API returns `403` with error code `insufficient_scope` and lists the required scopes in the response body." },
       { type: "callout", text: "Keep your API key secret. Do not expose it in client-side code or version control. If a key is compromised, revoke it immediately from the dashboard." }
     ],
     related: [
@@ -4438,10 +4453,11 @@ var sections17 = [
       { label: "Error Codes", slug: "error-codes" }
     ],
     faq: [
-      { question: "How do I authenticate with the Talonic API?", answer: "Include a Bearer token in the Authorization header of every request. API keys use the tlnc_ prefix and are scoped to a source." },
-      { question: "Where do I get an API key?", answer: "Create and manage API keys from Settings > API Keys in the Talonic dashboard." }
+      { question: "How do I authenticate with the Talonic API?", answer: "Include a Bearer token in the Authorization header of every request. API keys use the tlnc_ prefix." },
+      { question: "Where do I get an API key?", answer: "Create and manage API keys from Settings \u2192 API Keys in the Talonic dashboard." },
+      { question: "What scopes are available?", answer: "Four scopes: extract (submit documents), read (list/retrieve resources), write (create/update/delete resources), and billing (trigger credit top-ups). New keys get extract, read, and write by default; billing must be added explicitly." }
     ],
-    mentions: ["Bearer token", "API key", "Authorization header"]
+    mentions: ["Bearer token", "API key", "Authorization header", "scopes", "extract", "read", "write"]
   },
   {
     slug: "base-url",
@@ -4466,55 +4482,246 @@ var sections17 = [
     parentSlug: "overview",
     title: "Quick Start",
     seoTitle: "API Quick Start Guide \u2014 Talonic Docs",
-    description: "Get started with the Talonic API in three steps: extract a document with an inline schema, save the schema, and query extraction results.",
+    description: "Three modes, one API. Auto-detect extraction, schema-driven extraction, and document filtering \u2014 all with per-cell confidence and cost transparency.",
     content: [
-      { type: "paragraph", text: "Extract structured data from a document in three steps." },
-      { type: "heading", level: 3, id: "step-1", text: "1. Extract a document with an inline schema" },
-      { type: "code", language: "bash", title: "Step 1 \u2014 Extract", code: `curl -X POST https://api.talonic.com/v1/extract \\
-  -H "Authorization: Bearer tlnc_sk_live_7f3a...x9k2" \\
+      { type: "paragraph", text: "Three modes. One API. Auto-detect what's in the document. Send your own schema and get exactly that shape. Or skip the document entirely and query data you already ingested. Plus per-cell provenance, confidence scores, and cost transparency on every call." },
+      { type: "heading", level: 3, id: "prerequisites", text: "Prerequisites" },
+      { type: "list", items: [
+        "A Talonic account \u2014 sign up at [app.talonic.com](https://app.talonic.com)",
+        "An API key from **Settings \u2192 API Keys** (starts with `tlnc_`)",
+        "A PDF or image file to extract (e.g. an invoice)"
+      ] },
+      { type: "code", language: "bash", title: "Set your API key", code: `export TALONIC_API_KEY="tlnc_live_..."` },
+      { type: "heading", level: 2, id: "mode-1-auto-detect", text: "Mode 1 \u2014 Auto-detect extract" },
+      { type: "paragraph", text: "Send a document with no schema. Talonic discovers every field automatically." },
+      { type: "code", language: "bash", title: "curl \u2014 auto-detect all fields", code: `curl -X POST https://api.talonic.com/v1/extract \\
+  -H "Authorization: Bearer $TALONIC_API_KEY" \\
+  -F "file=@invoice.pdf"` },
+      { type: "paragraph", text: "Returns every field the AI discovers \u2014 vendor, dates, amounts, line items, addresses \u2014 with per-field confidence scores. Use this when you don't know the document structure upfront." },
+      { type: "heading", level: 2, id: "mode-2-schema-extract", text: "Mode 2 \u2014 Schema-driven extract" },
+      { type: "paragraph", text: "Send a document AND the shape you want. Get exactly those fields back." },
+      { type: "code", language: "bash", title: "curl \u2014 extract with inline schema", code: `curl -X POST https://api.talonic.com/v1/extract \\
+  -H "Authorization: Bearer $TALONIC_API_KEY" \\
   -F "file=@invoice.pdf" \\
-  -F 'schema={
-    "vendor_name": "string",
-    "invoice_number": "string",
-    "total_amount": "number",
-    "due_date": "date",
-    "line_items": [{
-      "description": "string",
-      "quantity": "number",
-      "unit_price": "number"
-    }]
-  }'` },
-      { type: "heading", level: 3, id: "step-2", text: "2. Save the schema for reuse" },
-      { type: "code", language: "bash", title: "Step 2 \u2014 Save schema", code: `curl -X POST https://api.talonic.com/v1/schemas \\
-  -H "Authorization: Bearer tlnc_sk_live_7f3a...x9k2" \\
+  -F 'schema={"vendor_name":"string","invoice_number":"string","total_amount":"number","due_date":"date"}'` },
+      { type: "paragraph", text: "The response contains exactly the four fields you asked for \u2014 nothing more. Save the schema with `POST /v1/schemas` for reuse across future extractions." },
+      { type: "heading", level: 2, id: "mode-3-filter", text: "Mode 3 \u2014 Query ingested data" },
+      { type: "paragraph", text: "Don't send a document. Query data you already extracted \u2014 across all documents in your workspace." },
+      { type: "code", language: "bash", title: "curl \u2014 filter previously extracted documents", code: `curl -X POST https://api.talonic.com/v1/documents/filter \\
+  -H "Authorization: Bearer $TALONIC_API_KEY" \\
   -H "Content-Type: application/json" \\
   -d '{
-    "name": "Invoice",
-    "definition": {
-      "vendor_name": "string",
-      "invoice_number": "string",
-      "total_amount": "number",
-      "due_date": "date",
-      "line_items": [{
-        "description": "string",
-        "quantity": "number",
-        "unit_price": "number"
-      }]
-    }
+    "conditions": [
+      { "fieldId": "vendor_name", "operator": "eq", "value": "Acme GmbH" }
+    ],
+    "limit": 50
   }'` },
-      { type: "heading", level: 3, id: "step-3", text: "3. Query your extraction results" },
-      { type: "code", language: "bash", title: "Step 3 \u2014 Retrieve", code: `curl https://api.talonic.com/v1/extractions?schema_id=sch_abc123 \\
-  -H "Authorization: Bearer tlnc_sk_live_7f3a...x9k2"` }
+      { type: "paragraph", text: "Returns all documents matching your filter \u2014 no re-extraction, no AI cost. Ingest once, query forever." },
+      { type: "heading", level: 2, id: "cost-transparency", text: "Cost on every call" },
+      { type: "paragraph", text: "Every synchronous extraction response includes cost headers so you can track spend per call:" },
+      { type: "code", language: "bash", title: "Cost headers", code: `X-Talonic-Cost-Credits: 12
+X-Talonic-Cost-EUR: 0.012
+X-Talonic-Balance-Credits: 64918
+X-Talonic-Cells-Resolved-Registry: 3
+X-Talonic-Cells-Resolved-AI: 5` },
+      { type: "paragraph", text: "Fields resolved from the registry (`X-Talonic-Cells-Resolved-Registry`) cost nothing. Only AI-resolved fields consume credits." },
+      { type: "heading", level: 2, id: "example-response", text: "Example response" },
+      { type: "paragraph", text: "A synchronous extraction returns structured data with confidence scores:" },
+      { type: "code", language: "json", title: "Response (200 OK)", code: `{
+  "extraction_id": "d1a2b3c4-5678-9abc-def0-1234567890ab",
+  "request_id": "req_x7y8z9a0b1c2d3e4",
+  "status": "complete",
+  "document": {
+    "id": "f0e1d2c3-b4a5-9687-8765-432109876543",
+    "filename": "invoice.pdf",
+    "pages": 2,
+    "type_detected": "Invoice"
+  },
+  "data": {
+    "vendor_name": "Acme GmbH",
+    "invoice_number": "INV-2025-0042",
+    "total_amount": 14250.00,
+    "due_date": "2025-04-15"
+  },
+  "confidence": {
+    "overall": 0.96,
+    "fields": {
+      "vendor_name": 0.97,
+      "invoice_number": 0.99,
+      "total_amount": 0.94,
+      "due_date": 0.99
+    }
+  },
+  "processing": {
+    "duration_ms": 1840,
+    "pages_processed": 2
+  }
+}` },
+      { type: "heading", level: 3, id: "next-steps", text: "Next steps" },
+      { type: "list", items: [
+        "**Reuse schemas** \u2014 save your schema with `POST /v1/schemas`, then pass `schema_id` on future extractions.",
+        "**Large documents** \u2014 files >5 pages return `202 Accepted` with a `poll_url`. See [Processing Modes](extract-processing-mode).",
+        "**Webhooks** \u2014 receive results via `extraction.complete` events instead of polling. See [Webhook Events](webhook-events).",
+        "**Batch mode** \u2014 process at 50% cost with `processing_mode=batch`. See [Batches](batches).",
+        "**Credits** \u2014 check your balance anytime with `GET /v1/credits/balance`. See [Credits](credits-balance)."
+      ] }
     ],
     related: [
       { label: "POST /v1/extract", slug: "post-extract" },
+      { label: "Filter Documents", slug: "filter-documents" },
       { label: "Schema Formats", slug: "extract-schemas" },
-      { label: "List Extractions", slug: "list-extractions" }
+      { label: "Processing Modes", slug: "extract-processing-mode" }
+    ],
+    faq: [
+      { question: "How do I get started with the Talonic API?", answer: "Three modes: (1) send a file with no schema for auto-detect, (2) send a file with a schema for exact extraction, (3) POST /v1/documents/filter to query already-ingested data." },
+      { question: "Do I need to create a schema first?", answer: "No. Mode 1 auto-detects all fields. Mode 2 accepts an inline schema. Save it with POST /v1/schemas later for reuse." },
+      { question: "Can I query previously extracted data without re-extracting?", answer: "Yes. POST /v1/documents/filter lets you search across all previously extracted documents by field values. No AI cost \u2014 ingest once, query forever." }
+    ],
+    mentions: ["curl", "quick start", "sync mode", "three modes", "auto-detect", "filter", "query", "cost headers"]
+  },
+  {
+    slug: "pagination",
+    parentSlug: "overview",
+    title: "Pagination",
+    seoTitle: "API Pagination \u2014 Talonic Docs",
+    description: "All list endpoints use cursor-based pagination with cursor, limit, and order parameters. Responses include next_cursor and has_more for iteration.",
+    content: [
+      { type: "paragraph", text: "All list endpoints use cursor-based pagination. Pass a `cursor` token from the previous response to fetch the next page." },
+      {
+        type: "param-table",
+        title: "Request parameters",
+        params: [
+          { name: "limit", type: "integer", description: "Number of items per page (1\u2013100, default 20).", default: "20" },
+          { name: "cursor", type: "string", description: "Opaque cursor token from `pagination.next_cursor` of the previous response. Omit for the first page." },
+          { name: "order", type: "string", description: "Sort direction: `asc` or `desc` (default `desc`, newest first).", default: "desc" }
+        ]
+      },
+      { type: "heading", level: 2, id: "pagination-response", text: "Response shape" },
+      {
+        type: "code",
+        title: "Paginated response",
+        code: `{
+  "data": [
+    { "id": "doc_x9y8z7w6", "name": "invoice-001.pdf", "..." : "..." },
+    { "id": "doc_a1b2c3d4", "name": "invoice-002.pdf", "..." : "..." }
+  ],
+  "pagination": {
+    "total": 1500,
+    "limit": 20,
+    "has_more": true,
+    "next_cursor": "YWJjMTIzfDIwMjYtMDQtMjVUMTQ6MzA6MDAuMDAwWg"
+  }
+}`
+      },
+      {
+        type: "param-table",
+        title: "Pagination object",
+        params: [
+          { name: "total", type: "integer", description: "Total number of items matching the query." },
+          { name: "limit", type: "integer", description: "Page size used for this request." },
+          { name: "has_more", type: "boolean", description: "`true` if there are more pages after this one." },
+          { name: "next_cursor", type: "string | null", description: "Cursor token to pass in the next request. `null` when on the last page." }
+        ]
+      },
+      { type: "heading", level: 2, id: "pagination-example", text: "Iterating through all pages" },
+      {
+        type: "code",
+        language: "bash",
+        title: "Python \u2014 paginate through all documents",
+        code: `import requests
+
+API_KEY = "tlnc_live_..."
+BASE = "https://api.talonic.com/v1"
+HEADERS = {"Authorization": f"Bearer {API_KEY}"}
+
+cursor = None
+all_documents = []
+
+while True:
+    params = {"limit": 100}
+    if cursor:
+        params["cursor"] = cursor
+
+    resp = requests.get(f"{BASE}/documents", headers=HEADERS, params=params)
+    page = resp.json()
+
+    all_documents.extend(page["data"])
+
+    if not page["pagination"]["has_more"]:
+        break
+    cursor = page["pagination"]["next_cursor"]
+
+print(f"Fetched {len(all_documents)} documents")`
+      },
+      { type: "callout", text: "Cursors are opaque tokens \u2014 do not parse, modify, or store them long-term. They may change format without notice." }
+    ],
+    related: [
+      { label: "List Documents", slug: "list-documents" },
+      { label: "List Extractions", slug: "list-extractions" },
+      { label: "Rate Limits", slug: "rate-limits" }
+    ],
+    faq: [
+      { question: "How does Talonic API pagination work?", answer: "Cursor-based. Pass limit (1-100, default 20) and cursor (from pagination.next_cursor). Response includes data[], pagination.has_more, and pagination.next_cursor." },
+      { question: "What is the maximum page size?", answer: "100 items per page. Default is 20." }
+    ],
+    mentions: ["pagination", "cursor", "next_cursor", "has_more", "limit"]
+  },
+  {
+    slug: "idempotency",
+    parentSlug: "overview",
+    title: "Idempotency",
+    seoTitle: "API Idempotency \u2014 Talonic Docs",
+    description: "Use the Idempotency-Key header to safely retry POST requests without creating duplicate extractions. Keys are valid for 24 hours.",
+    content: [
+      { type: "paragraph", text: "Pass an `Idempotency-Key` header on POST requests to safely retry without creating duplicate work. If a request with the same key has already been processed, the API returns the cached response." },
+      {
+        type: "param-table",
+        title: "Idempotency details",
+        params: [
+          { name: "Header", type: "", description: "`Idempotency-Key: <your-unique-key>`" },
+          { name: "Supported endpoints", type: "", description: "`POST /v1/extract` (primary use case). Other POST endpoints may honor it in the future." },
+          { name: "Key format", type: "", description: "Any string up to 255 characters. UUIDs recommended." },
+          { name: "TTL", type: "", description: "24 hours. After expiry, the same key can be reused." },
+          { name: "Scope", type: "", description: "Per API key (customer). The same idempotency key used by different API keys are independent." }
+        ]
+      },
+      { type: "heading", level: 2, id: "idempotency-behavior", text: "Behavior" },
+      { type: "list", items: [
+        "**First request** \u2014 processed normally. The response and extraction ID are cached against the key.",
+        "**Duplicate request** (same key within 24h) \u2014 returns the cached response immediately with HTTP 200. No new extraction is created.",
+        "**Expired key** (after 24h) \u2014 treated as a new request."
+      ] },
+      {
+        type: "code",
+        language: "bash",
+        title: "Example \u2014 safe retry with idempotency",
+        code: `# Generate a unique key per logical operation
+IDEMPOTENCY_KEY=$(uuidgen)
+
+curl -X POST https://api.talonic.com/v1/extract \\
+  -H "Authorization: Bearer $TALONIC_API_KEY" \\
+  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \\
+  -F "file=@invoice.pdf" \\
+  -F 'schema={"vendor_name":"string","total_amount":"number"}'
+
+# Safe to retry on network timeout \u2014 same key returns cached result
+curl -X POST https://api.talonic.com/v1/extract \\
+  -H "Authorization: Bearer $TALONIC_API_KEY" \\
+  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \\
+  -F "file=@invoice.pdf" \\
+  -F 'schema={"vendor_name":"string","total_amount":"number"}'`
+      },
+      { type: "callout", text: "Always use a new idempotency key for each distinct logical operation. Reusing a key with different parameters will return the cached result from the first request, not process the new parameters." }
+    ],
+    related: [
+      { label: "POST /v1/extract", slug: "post-extract" },
+      { label: "Error Codes", slug: "error-codes" }
     ],
     faq: [
-      { question: "How do I get started with the Talonic API?", answer: "Extract a document with an inline schema, save the schema for reuse, then query your extraction results. See the Quick Start guide for curl examples." }
+      { question: "How do I prevent duplicate extractions on retry?", answer: "Pass an Idempotency-Key header with a unique value (e.g. UUID) on POST /v1/extract. Retries with the same key return the cached result." },
+      { question: "How long are idempotency keys valid?", answer: "24 hours. After that, the same key can be reused and will trigger a new extraction." }
     ],
-    mentions: ["curl", "schema", "extraction", "document"]
+    mentions: ["idempotency", "Idempotency-Key", "retry", "duplicate"]
   }
 ];
 
@@ -4665,9 +4872,34 @@ var sections18 = [
           { name: "400", type: "invalid_options", description: "The options field is not valid JSON." },
           { name: "401", type: "unauthorized", description: "Missing or invalid API key." },
           { name: "422", type: "extraction_failed", description: "Extraction completed but produced no usable output. Check the document quality or schema definition." },
-          { name: "429", type: "rate_limited", description: "Too many requests. Retry after the period indicated in the Retry-After header." }
+          { name: "429", type: "rate_limited", description: "Too many requests. Check X-RateLimit-Reset for when the window resets." }
         ]
-      }
+      },
+      { type: "heading", level: 2, id: "post-extract-cost-headers", text: "Cost Headers" },
+      { type: "paragraph", text: "Synchronous 200 responses include cost transparency headers so you can track spend per call without a separate API round-trip:" },
+      {
+        type: "param-table",
+        title: "Cost response headers",
+        params: [
+          { name: "X-Talonic-Cost-Credits", type: "integer", description: "Credits consumed by this extraction." },
+          { name: "X-Talonic-Cost-EUR", type: "number", description: "EUR cost of this extraction." },
+          { name: "X-Talonic-Balance-Credits", type: "integer", description: "Remaining credit balance after this call." },
+          { name: "X-Talonic-Cells-Resolved-Registry", type: "integer", description: "Fields resolved from the registry (no AI cost)." },
+          { name: "X-Talonic-Cells-Resolved-AI", type: "integer", description: "Fields resolved by the AI model." }
+        ]
+      },
+      {
+        type: "code",
+        language: "bash",
+        title: "Cost headers on a sync response",
+        code: `HTTP/1.1 200 OK
+X-Talonic-Cost-Credits: 12
+X-Talonic-Cost-EUR: 0.012
+X-Talonic-Balance-Credits: 64918
+X-Talonic-Cells-Resolved-Registry: 3
+X-Talonic-Cells-Resolved-AI: 5`
+      },
+      { type: "callout", text: "Cost headers are only present on synchronous (200) responses. For async (202) extractions, check the credits balance endpoint or listen for the `extraction.complete` webhook which includes cost data." }
     ],
     related: [
       { label: "Schema Formats", slug: "extract-schemas" },
@@ -7601,7 +7833,7 @@ function verifyWebhook(payload, signature, secret) {
         title: "Test inputs",
         code: `Secret:    whsec_test_secret_do_not_use_in_production
 Payload:   {"event":"extraction.complete","delivery_id":"dlv_test123","timestamp":"2026-01-15T10:00:00Z","data":{"extraction_id":"ext_abc","document_id":"doc_xyz","schema_id":"sch_123","status":"complete","confidence":0.95}}
-Expected signature: sha256=a4f2b8c1d3e5f7a9b0c2d4e6f8a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9e1f3a5`
+Expected signature: sha256=1e23bdc14b051f268d4fd9544387b51b074186c51c5b6c76ce700956308d168a`
       },
       {
         type: "code",
@@ -7611,7 +7843,7 @@ Expected signature: sha256=a4f2b8c1d3e5f7a9b0c2d4e6f8a1b3c5d7e9f0a2b4c6d8e0f1a3b
 echo -n '{"event":"extraction.complete","delivery_id":"dlv_test123","timestamp":"2026-01-15T10:00:00Z","data":{"extraction_id":"ext_abc","document_id":"doc_xyz","schema_id":"sch_123","status":"complete","confidence":0.95}}' \\
   | openssl dgst -sha256 -hmac "whsec_test_secret_do_not_use_in_production"
 
-# Output: a4f2b8c1d3e5f7a9b0c2d4e6f8a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9e1f3a5`
+# Output: 1e23bdc14b051f268d4fd9544387b51b074186c51c5b6c76ce700956308d168a`
       },
       { type: "callout", text: "The test secret above is for development only. Never use it in production. Your real webhook secret is generated when you configure a webhook in the dashboard." }
     ],
@@ -17118,21 +17350,36 @@ var sections44 = [
     parentSlug: "errors-rate-limits",
     title: "Error Format",
     seoTitle: "API Error Format \u2014 Talonic Docs",
-    description: "All Talonic API errors return a consistent JSON structure with a machine-readable code, human-readable message, HTTP status, retryable flag, and request ID.",
+    description: "All Talonic API errors return a consistent JSON envelope with a machine-readable code, human-readable message, HTTP status, retryable flag, request ID, and timestamp.",
     content: [
-      { type: "paragraph", text: "All errors return a consistent JSON structure with a machine-readable code and a human-readable message." },
+      { type: "paragraph", text: "All errors return a consistent JSON envelope. The `retryable` field tells you whether the request can be retried with the same parameters." },
       {
         type: "code",
-        title: "Error response shape",
+        title: "Error response envelope",
         code: `{
-  "error": {
-    "code": "invalid_schema",
-    "message": "Schema definition is missing required 'type' field at path 'line_items.items'.",
-    "status": 400,
-    "retryable": false,
-    "request_id": "req_x7y8z9a0"
-  }
+  "statusCode": 400,
+  "code": "VALIDATION_ERROR",
+  "error": "Bad Request",
+  "message": "Schema definition is missing required 'type' field at path 'line_items.items'.",
+  "retryable": false,
+  "request_id": "req_x7y8z9a0b1c2d3e4",
+  "timestamp": "2026-04-25T14:30:00.000Z",
+  "path": "/v1/schemas"
 }`
+      },
+      {
+        type: "param-table",
+        title: "Envelope fields",
+        params: [
+          { name: "statusCode", type: "integer", description: "HTTP status code (matches the response status)." },
+          { name: "code", type: "string", description: "Machine-readable error code (e.g. `VALIDATION_ERROR`, `RATE_LIMIT_EXCEEDED`)." },
+          { name: "error", type: "string", description: 'HTTP status text (e.g. "Bad Request", "Too Many Requests").' },
+          { name: "message", type: "string", description: "Human-readable explanation of what went wrong." },
+          { name: "retryable", type: "boolean", description: "`true` if the same request may succeed on retry (e.g. rate limits, timeouts)." },
+          { name: "request_id", type: "string", description: "Unique request identifier for support debugging. Prefix: `req_`." },
+          { name: "timestamp", type: "string", description: "ISO 8601 timestamp of when the error occurred." },
+          { name: "path", type: "string", description: "The request path that produced the error." }
+        ]
       }
     ],
     related: [
@@ -17140,41 +17387,66 @@ var sections44 = [
       { label: "Rate Limits", slug: "rate-limits" }
     ],
     faq: [
-      { question: "What does a Talonic API error look like?", answer: "A JSON object with error.code (machine-readable), error.message (human-readable), error.status (HTTP status), error.retryable (boolean), and error.request_id." }
+      { question: "What does a Talonic API error look like?", answer: "A JSON object with statusCode, code (machine-readable), message (human-readable), retryable (boolean), request_id, timestamp, and path." },
+      { question: "How do I know if an error is retryable?", answer: "Check the retryable field in the error response. If true, you can retry with exponential backoff." }
     ],
-    mentions: ["error format", "JSON error", "request_id"]
+    mentions: ["error format", "JSON error", "request_id", "retryable"]
   },
   {
     slug: "error-codes",
     parentSlug: "errors-rate-limits",
     title: "Error Codes",
     seoTitle: "API Error Codes Reference \u2014 Talonic Docs",
-    description: "Complete reference of Talonic API error codes including bad_request, invalid_schema, unauthorized, not_found, rate_limited, and more with HTTP status mappings.",
+    description: "Complete reference of Talonic API error codes with HTTP status, retryable classification, and recommended handling for each error type.",
     content: [
-      { type: "paragraph", text: "Error codes returned by the Talonic API:" },
+      { type: "paragraph", text: "Error codes returned by the Talonic API, grouped by whether they are retryable:" },
+      { type: "heading", level: 2, id: "permanent-errors", text: "Permanent errors (do not retry)" },
       { type: "list", items: [
-        "**400** `bad_request` \u2014 The request body is malformed or missing required fields.",
+        "**400** `VALIDATION_ERROR` \u2014 The request body is malformed or missing required fields.",
         "**400** `invalid_schema` \u2014 The schema definition is invalid or contains unsupported types.",
         "**400** `invalid_file` \u2014 The uploaded file is corrupt, empty, or in an unsupported format.",
-        "**401** `unauthorized` \u2014 Missing or invalid API key.",
-        "**403** `forbidden` \u2014 The API key does not have permission for this operation.",
-        "**404** `not_found` \u2014 The requested resource does not exist.",
-        "**409** `conflict` \u2014 The resource has been modified. Retry with the latest version.",
-        "**413** `file_too_large` \u2014 The uploaded file exceeds the 50MB size limit.",
-        "**422** `unprocessable` \u2014 The document could not be parsed. Try a different file format.",
-        "**429** `rate_limited` \u2014 Rate limit exceeded. Check response headers for reset time.",
-        "**500** `internal_error` \u2014 An unexpected error occurred. This is retryable.",
+        "**401** `AUTH_REQUIRED` \u2014 Missing or invalid API key.",
+        "**401** `TOKEN_EXPIRED` \u2014 The API key has expired. Generate a new one from the dashboard.",
+        "**402** `INSUFFICIENT_CREDITS` \u2014 Your workspace has no remaining credits. Top up from Settings \u2192 Billing.",
+        "**403** `INSUFFICIENT_PERMISSIONS` \u2014 The API key does not have the required scope for this operation.",
+        "**404** `RESOURCE_NOT_FOUND` \u2014 The requested resource does not exist.",
+        "**409** `DUPLICATE_RESOURCE` \u2014 A resource with this identifier already exists.",
+        "**413** `FILE_TOO_LARGE` \u2014 The uploaded file exceeds the maximum size limit (500 MB).",
+        "**422** `EXTRACTION_FAILED` \u2014 The document could not be processed. Try a different format or check the file."
+      ] },
+      { type: "heading", level: 2, id: "retryable-errors", text: "Retryable errors (retry with backoff)" },
+      { type: "list", items: [
+        "**429** `RATE_LIMIT_EXCEEDED` \u2014 Daily rate limit reached. Wait until `X-RateLimit-Reset` before retrying.",
+        "**429** `LLM_RATE_LIMITED` \u2014 Upstream AI provider rate limit. Retry after 30\u201360 seconds.",
+        "**500** `INTERNAL_ERROR` \u2014 An unexpected server error occurred. Retryable with backoff.",
+        "**500** `LLM_TIMEOUT` \u2014 Upstream AI provider timed out. Retryable with backoff.",
+        "**500** `LLM_UNAVAILABLE` \u2014 Upstream AI provider temporarily unavailable.",
+        "**500** `OCR_FAILED` \u2014 Document OCR failed. Retryable \u2014 may succeed on retry.",
+        "**500** `EXTRACTION_TIMEOUT` \u2014 Extraction exceeded the time limit. Retryable for smaller documents.",
         "**503** `service_unavailable` \u2014 The service is temporarily unavailable. Retry with backoff."
-      ] }
+      ] },
+      { type: "heading", level: 2, id: "backoff-strategy", text: "Recommended backoff strategy" },
+      { type: "paragraph", text: "For retryable errors, use exponential backoff with jitter:" },
+      { type: "list", ordered: true, items: [
+        "1st retry \u2014 wait 1 second",
+        "2nd retry \u2014 wait 2 seconds",
+        "3rd retry \u2014 wait 4 seconds",
+        "4th retry \u2014 wait 8 seconds",
+        "5th retry (max) \u2014 wait 16 seconds"
+      ] },
+      { type: "paragraph", text: "Add random jitter (\xB120%) to avoid thundering herd. For `429` errors specifically, respect the `X-RateLimit-Reset` header instead of using fixed backoff \u2014 it tells you exactly when the window resets (ISO 8601 timestamp, midnight UTC)." },
+      { type: "callout", text: "The API does not send a `Retry-After` header. For rate limits, use `X-RateLimit-Reset` to determine when to retry. For other retryable errors, use exponential backoff." }
     ],
     related: [
       { label: "Error Format", slug: "error-format" },
       { label: "Rate Limits", slug: "rate-limits" }
     ],
     faq: [
-      { question: "What error codes does the Talonic API return?", answer: "Standard HTTP status codes (400, 401, 403, 404, 409, 413, 422, 429, 500, 503) with machine-readable codes like bad_request, invalid_schema, unauthorized, rate_limited, etc." }
+      { question: "What error codes does the Talonic API return?", answer: "Errors use HTTP status codes (400\u2013503) with machine-readable codes like VALIDATION_ERROR, RATE_LIMIT_EXCEEDED, INSUFFICIENT_CREDITS, INTERNAL_ERROR, etc." },
+      { question: "Which errors should I retry?", answer: "Retry errors with retryable: true \u2014 typically 429 (rate limited), 500 (internal/timeout), and 503 (unavailable). Never retry 400, 401, 402, 403, 404, or 413." },
+      { question: "Does the API send a Retry-After header?", answer: "No. For rate limits, use X-RateLimit-Reset (ISO 8601 timestamp). For other retryable errors, use exponential backoff starting at 1 second." }
     ],
-    mentions: ["error codes", "HTTP status", "bad_request", "rate_limited"]
+    mentions: ["error codes", "HTTP status", "retryable", "backoff", "RATE_LIMIT_EXCEEDED", "INSUFFICIENT_CREDITS"]
   },
   {
     slug: "rate-limits",
@@ -17186,15 +17458,15 @@ var sections44 = [
       { type: "paragraph", text: "API rate limits depend on your plan tier. Limits are applied per API key on a rolling daily window (UTC midnight reset)." },
       { type: "paragraph", text: "Rate limits by plan:" },
       { type: "list", items: [
-        "**Free** \u2014 50 extractions/day, 5/min burst, 10 MB max file size",
-        "**Pro** \u2014 2,000 extractions/day, 30/min burst, 50 MB max file size",
-        "**Enterprise** \u2014 Unlimited extractions, custom burst rate, custom file size"
+        "**Free** \u2014 50 extractions/day, 5/min burst, 20 MB max file size",
+        "**Pro** \u2014 2,000 extractions/day, 30/min burst, 100 MB max file size",
+        "**Enterprise** \u2014 Unlimited extractions, custom burst rate, 500 MB max file size"
       ] },
       { type: "paragraph", text: "Every API response includes rate limit headers:" },
       { type: "list", items: [
         "`X-RateLimit-Limit` \u2014 Maximum number of requests allowed in the current window.",
         "`X-RateLimit-Remaining` \u2014 Number of requests remaining in the current window.",
-        "`X-RateLimit-Reset` \u2014 Unix timestamp when the rate limit window resets."
+        "`X-RateLimit-Reset` \u2014 ISO 8601 timestamp when the rate limit window resets (midnight UTC)."
       ] },
       {
         type: "code",
@@ -17203,7 +17475,7 @@ var sections44 = [
         code: `HTTP/1.1 200 OK
 X-RateLimit-Limit: 2000
 X-RateLimit-Remaining: 1847
-X-RateLimit-Reset: 1726358400`
+X-RateLimit-Reset: 2026-04-26T00:00:00.000Z`
       },
       { type: "callout", text: "When you receive a `429` response, wait until the `X-RateLimit-Reset` timestamp before retrying. Implement exponential backoff for the best experience." }
     ],

package/dist/index.js

@@ -6378,7 +6378,9 @@ var API_NAV_SECTIONS = [
     { id: "introduction", label: "Introduction" },
     { id: "authentication", label: "Authentication" },
     { id: "base-url", label: "Base URL" },
-    { id: "quick-start", label: "Quick Start" }
+    { id: "quick-start", label: "Quick Start" },
+    { id: "pagination", label: "Pagination" },
+    { id: "idempotency", label: "Idempotency" }
   ] },
   { id: "extract", label: "Extract", children: [
     { id: "post-extract", label: "POST /v1/extract" },