{
  "contract": "ThroughlineLaunchFoundationV1",
  "facts_version": "2026-11-13.1",
  "operator": {"name": "Michael O'Rourke", "contact": "access@throughline.markets", "trading_disclosure": "The operator also trades on Polymarket. His trading system processes news matches before API customers receive them. No interval has been measured, not every match leads to a trade, and delivery at the same moment is not offered.", "terms": "https://throughline.markets/terms", "privacy": "https://throughline.markets/privacy"},
  "verified_on": "2026-11-13",
  "derived_from": {
    "what": "Hosted source and configuration verification, public route/authentication canaries and an existing account noncharged usage check.",
    "source_commit": "d8d2f2c",
    "release_status": "Installed and checked on 2026-11-12. Public routes, authentication and noncharged usage passed; real browser approval and paid checkout flows require their own tests."
  },
  "base_url": "https://api.throughline.markets",
  "account_url": "https://api.throughline.markets/account",
  "docs_url": "https://throughline.markets/api",
  "client_repo": "https://github.com/mokn/throughline",
  "contact": "access@throughline.markets",
  "api_key_env": "THROUGHLINE_API_KEY",
  "api_key_pattern": "^tl_live_[A-Za-z0-9_-]{43}$",
  "agent_token_pattern": "^tl_agent_[A-Za-z0-9_-]{43}$",
  "auth": {
    "feed": "Authorization: Bearer <API key>",
    "account": "Browser sign-in session from the account page, or, on the routes that name a scope, a connection's management credential holding that scope. A feed API key cannot manage accounts.",
    "agent": "Authorization: Bearer <management credential>. Issued only through an approved pairing, limited to the scopes the person approved, and never accepted with an Origin header.",
    "pairing": "POST /auth/v1/pairings and POST /auth/v1/token take no credential. The device code in the body is the secret.",
    "sign_in_providers_now": ["Google", "GitHub"],
    "sign_in_providers_upcoming": []
  },
  "plans": [
    {"wire": "free", "label": "Free", "price_usd_month": 0, "news_responses_per_day": 100, "card": false},
    {"wire": "evaluation", "label": "Trial", "price_usd_month": 0, "news_responses_per_day": 5000, "days": 7, "card": false, "explicit_start": true},
    {"wire": "builder", "label": "Builder", "price_usd_month": 29, "news_responses_per_day": 5000, "card": true}
  ],
  "quota": {
    "window": "UTC day (86,400 seconds)",
    "charged": "Each HTTP 200 from a news route counts once, including an empty page and a cursor=latest head capture.",
    "not_charged": "Error responses.",
    "coverage": "GET /v1/coverage has its own separate allowance. Its responses carry the X-RateLimit headers of the news allowance, which a coverage read does not reduce.",
    "shared": "All keys on an account share one allowance. Creating or revoking a key does not reset it.",
    "overage": "None. There are no automatic overage charges."
  },
  "polling": [
    {"every": "15 minutes", "responses_per_day": 96, "fits": ["free", "evaluation", "builder"]},
    {"every": "30 seconds", "responses_per_day": 2880, "fits": ["evaluation", "builder"]}
  ],
  "service_limits": {"requests_per_ip_per_window": 240, "burst_window_seconds": 60, "news_page_size": 20, "active_keys_per_account": 5, "request_body_bytes": 65536, "feed_response_bytes": 262144, "account_news_bytes_per_utc_day": 2147483648, "source": "Running hosted customer configuration, verified 2026-11-12."},
  "rate_limit_headers": ["X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset"],
  "routes": [
    {"method": "GET", "path": "/", "auth": "none", "charged": false, "query": []},
    {"method": "GET", "path": "/v1/news", "auth": "api_key", "charged": true, "query": ["cursor", "limit", "market_id"]},
    {"method": "GET", "path": "/v1/markets/{condition_id}/news", "auth": "api_key", "charged": true, "query": ["cursor", "limit", "market_id"]},
    {"method": "GET", "path": "/v1/news/{record_id}", "auth": "api_key", "charged": true, "query": ["stream_id"]},
    {"method": "GET", "path": "/v1/coverage", "auth": "api_key", "charged": false, "query": []},
    {"method": "GET", "path": "/v1/usage", "auth": "api_key", "charged": false, "query": []},
    {"method": "POST", "path": "/auth/v1/pairings", "auth": "none", "charged": false, "query": []},
    {"method": "POST", "path": "/auth/v1/token", "auth": "none", "charged": false, "query": []},
    {"method": "GET", "path": "/account/v1/pairings/{user_code}", "auth": "session", "charged": false, "query": []},
    {"method": "POST", "path": "/account/v1/pairings/{user_code}", "auth": "session", "charged": false, "query": []},
    {"method": "GET", "path": "/account/v1/connection", "auth": "agent", "charged": false, "query": []},
    {"method": "DELETE", "path": "/account/v1/connection", "auth": "agent", "charged": false, "query": []},
    {"method": "GET", "path": "/account/v1/audit", "auth": "session_or_own_agent", "charged": false, "query": ["cursor"]},
    {"method": "GET", "path": "/account/v1/connections", "auth": "session", "charged": false, "query": ["cursor"]},
    {"method": "DELETE", "path": "/account/v1/connections/{connection_id}", "auth": "session", "charged": false, "query": []},
    {"method": "GET", "path": "/account/v1/me", "auth": "session_or_agent", "scope": "account:read", "charged": false, "query": []},
    {"method": "POST", "path": "/account/v1/trial", "auth": "session", "charged": false, "query": []},
    {"method": "GET", "path": "/account/v1/keys", "auth": "session_or_agent", "scope": "keys:read", "charged": false, "query": ["cursor", "order"]},
    {"method": "POST", "path": "/account/v1/keys", "auth": "session_or_agent", "scope": "keys:write", "charged": false, "query": []},
    {"method": "DELETE", "path": "/account/v1/keys/{key_id}", "auth": "session_or_agent", "scope": "keys:write", "charged": false, "query": []},
    {"method": "GET", "path": "/account/v1/billing/read", "auth": "session_or_agent", "scope": "billing:read", "charged": false, "query": []},
    {"method": "GET", "path": "/account/v1/billing/status", "auth": "session", "charged": false, "query": []},
    {"method": "POST", "path": "/account/v1/billing/checkout", "auth": "session", "charged": false, "query": []},
    {"method": "POST", "path": "/account/v1/billing/portal", "auth": "session", "charged": false, "query": []}
  ],
  "delegated_access": {
    "summary": "A program asks for access with a pairing. One signed-in person opens the link, checks the code, chooses the permissions and approves or denies. The program then collects a receipt with key and connection details.",
    "scopes": [
      {"scope": "news:read", "grants": "A feed API key for the news, coverage and usage routes. Always part of a pairing."},
      {"scope": "account:read", "grants": "GET /account/v1/me, without its billing fields."},
      {"scope": "keys:read", "grants": "GET /account/v1/keys."},
      {"scope": "keys:write", "grants": "POST /account/v1/keys and DELETE /account/v1/keys/{key_id}. Account-wide: it can revoke any key on the account, including ones made in the account page, and new keys use the account's shared key slots."},
      {"scope": "billing:read", "grants": "GET /account/v1/billing/read."}
    ],
    "secrets": "The program generates the feed key and, when it asks for more than news:read, a management credential, and sends only their SHA-256 hashes. Throughline activates the hashes on approval. Clients send the credentials as HTTPS bearer tokens when they use them.",
    "create": "POST /auth/v1/pairings with exactly name, scopes, feed_key_hash and management_token_hash. management_token_hash is null exactly when scopes is [\"news:read\"]. The two hashes must differ.",
    "created_fields": ["pairing_id", "device_code", "user_code", "expires_in", "interval", "verification_uri", "verification_uri_complete"],
    "user_code_pattern": "^[A-HJ-NP-Z2-9]{4}-[A-HJ-NP-Z2-9]{4}$",
    "device_code_pattern": "^[A-Za-z0-9_-]{43}$",
    "poll": "POST /auth/v1/token with exactly device_code, no more often than interval seconds. Pending, denied and expired are all HTTP 400, told apart by error; an approved pairing answers 200 with status delivered.",
    "delivered_fields": {"status": "delivered", "key": ["id", "name", "created_at"], "connection": ["id", "name", "scopes", "created_at", "expires_at"]},
    "consent": "GET /account/v1/pairings/{user_code} shows the request; POST with exactly decision (approve or deny), scopes and start_trial decides it. Browser sign-in session only. The approved scopes are a subset of the requested ones and always include news:read. start_trial true also starts the seven-day trial.",
    "connections": "GET /account/v1/connections lists connections in ID order with their scopes, keys and last use; next_cursor is null on the last page. DELETE /account/v1/connections/{connection_id} revokes the connection, its management credential and every key it holds. Browser sign-in session only.",
    "browser_only": ["Approving or denying a pairing", "Listing and revoking connections", "Starting the trial", "Checkout, the billing portal and provider billing status"],
    "expiry": "expires_in is the approval window. connection.expires_at is when the management credential stops working. A feed key issued through a pairing has no expiry of its own; it works until it or its connection is revoked.",
    "expired_token_is_not_proof": "expired_token after a pairing was started is not proof that nobody approved it. If approval happened and the receipt was not collected in time, the key is active. The person must look at Your connections in the account page and revoke the named connection if it is not wanted.",
    "release_contract_durations": "The hosted configuration sets a ten-minute approval window, a five-second poll interval, a 24-hour receipt window and a 30-day management credential. Read expires_in, interval and connection.expires_at from the responses.",
    "client": "The throughline command in the public client repository implements this flow and keeps the secrets in private files.",
    "client_version": "0.3.0",
    "client_pin": "df5cd8a0bc6aa063bd9da9ca37c33115f54096f2",
    "client_install": "python3 -m pip install \"git+https://github.com/mokn/throughline@df5cd8a0bc6aa063bd9da9ca37c33115f54096f2\"",
    "client_statuses": ["ok", "pending", "delivered", "denied", "slow_down", "cancelled", "delivery_unknown", "error"],
    "client_exit_codes": {"0": "success", "2": "pending or slow down; run again later", "3": "denied or cancelled", "4": "error or delivery unknown"},
    "client_files": {"feed_key": ".env", "pending": ".throughline/pending.json", "management": ".throughline/credentials.json"},
    "payment": "Payment is never delegated. Checkout and the billing portal need the person's own browser session."
  },
  "usage_route": {
    "route": "GET /v1/usage",
    "returns": ["plan", "usage"],
    "charged": "Not counted against the news allowance. It has its own separate allowance and sends no X-RateLimit headers.",
    "request": "No query string and no body."
  },
  "cursor_start": {
    "routes": ["/v1/news", "/v1/markets/{condition_id}/news"],
    "default": "cursor=0, also the default when cursor is omitted, replays from the start of retained history.",
    "latest": "cursor=latest returns a successful empty page: items is empty, has_more is false and next_cursor is the current head as a number.",
    "global": "The head is the head of the whole feed, also when a market filter or the market route is used.",
    "charged": "A successful head capture counts as one news response.",
    "persist": "Save the returned number before polling and reuse it after a restart. Send latest once per consumer, never on every poll: each repeat skips whatever arrived in between.",
    "exact": "Only the exact lower-case word latest is accepted; anything else that is not digits is 400 invalid_pagination.",
    "clients": "Reference-client helpers that start from now (start_from_now in Python, startFromNow in JavaScript) send this call and need a server running this release."
  },
  "key_listing": {
    "route": "GET /account/v1/keys",
    "default": "Without order, keys come in ID order. next_cursor is the last ID on the page; continue until a page has no items.",
    "newest": "order=newest returns keys newest first, by creation time then ID, both descending. next_cursor is null on the last page.",
    "cursor": "A 32-character lower-case hexadecimal key ID from next_cursor. With order=newest it must be a key on the same account, otherwise 400 invalid_cursor.",
    "order_values": ["newest"],
    "secrets": "Listings include revoked keys and never include a secret."
  },
  "entry_points": {
    "root": {"request": "GET /", "auth": "none", "charged": false, "returns": {"name": "Throughline API", "account": "/account", "docs": "https://throughline.markets/api", "agents": "https://throughline.markets/agents.md"}, "note": "Public pointers only. Other methods on / are not this document."},
    "account_redirect": "GET /account/ and GET /account with any query string answer 303 to the fixed /account. The query is discarded and never copied into the redirect."
  },
  "enums": {
    "schema": ["ThroughlinePublicationV3"],
    "operation": ["upsert", "withdraw"],
    "source_revision_kind": ["captured_feed_revision"],
    "source_clock_status": ["reported", "unreliable", "missing"],
    "captured_content": ["headline_only", "summary", "body"],
    "publisher_completeness": ["unknown"],
    "relevance_stage": ["scout"],
    "verdict": ["relevant", "uncertain"],
    "novelty": ["new", "update", "repeat", "uncertain"],
    "explanation_kind": ["unavailable", "public_explanation"],
    "analysis_stage": ["analyst"],
    "report_status": ["reported", "unverified", "contradicted", "repeat"],
    "impact": [0, 1, 2, 3, 4],
    "publisher_availability_status": ["available", "delayed", "unavailable", "unknown"],
    "plan": ["free", "evaluation", "builder"]
  },
  "coverage_fixed_fields": {
    "schema": "ThroughlineCoverageV1",
    "screened_coverage": null,
    "screened_coverage_status": "unknown",
    "source_policy": {
      "start": "activation",
      "historical_backfill": false,
      "match_evidence": "primary_article_alone",
      "unsupported_evidence": ["related_article_only", "mixed_articles", "previous_article_only"],
      "source_loss_before_public_commit": "possible",
      "dynamic_source_status": "unknown",
      "research_archive": false
    }
  },
  "error_shape": {
    "body": "{\"error\": \"<code>\", \"message\": \"<text>\", \"docs_url\": \"https://throughline.markets/api#errors\", \"request_id\": \"<32 hex>\"}",
    "stable": "error is the stable code; branch on it. message is the code in words, for people, and may change. docs_url is fixed. request_id identifies the request and matches the X-Request-ID response header, which every response from the API routes carries.",
    "extra": "Feed quota errors account_quota_exceeded and account_data_limit also carry a usage object, upgrade_url, reset_at and the X-RateLimit headers. A pairing still waiting for a decision also carries status pending.",
    "headers": "Every 401 carries WWW-Authenticate: Bearer realm=\"throughline\". Responses that name a wait carry Retry-After in seconds.",
    "additive": "New fields may be added to an error body. Clients must ignore fields they do not know.",
    "plain_404": "A 404 with an empty body is not an API error: it comes from the public proxy for a path or method it does not forward, or from the account page and its files for a non-GET request, or from one of those files requested with a query string."
  },
  "errors": [
    {"code": "unauthorized", "status": 401, "surface": "feed, account, billing", "meaning": "On account and billing routes: the Authorization header is missing or malformed, or the sign-in session is not valid. On a feed route it appears only when a key is revoked or its account removed while the request is being served.", "recovery": "Account page: sign in again. Feed: treat as invalid_key. Do not retry unchanged."},
    {"code": "missing_or_malformed_key", "status": 401, "surface": "feed", "meaning": "A feed route was called with no Authorization header, or one that is not exactly 'Bearer <key>' with a well-formed API key. Nothing was looked up.", "recovery": "Fix the client: read THROUGHLINE_API_KEY and send 'Authorization: Bearer <key>'. A new key is not needed. Do not retry unchanged."},
    {"code": "invalid_key", "status": 401, "surface": "feed, account", "meaning": "A well-formed credential that is unknown, revoked or expired: a feed API key on a feed route, or a connection's management credential on an account route.", "recovery": "Stop and tell the person. They can create a key in the account page or approve a new pairing. Do not retry unchanged."},
    {"code": "account_unavailable", "status": 403, "surface": "feed, account, billing, pairing", "meaning": "The account behind the key, session or approved pairing is disabled.", "recovery": "Stop. Email access@throughline.markets."},
    {"code": "origin_forbidden", "status": 403, "surface": "feed, account, billing, pairing", "meaning": "The request carried an Origin header from another website, or a management credential was sent with any Origin header. Browsers on other sites may not call the API.", "recovery": "Call the API from a server, script or command-line program, not from browser JavaScript."},
    {"code": "verified_identity_required", "status": 403, "surface": "account", "meaning": "A browser-only account operation was attempted without a verified sign-in session: approving a pairing or managing connections with a management credential, for example.", "recovery": "The person signs in at the account page and does it there. API keys and management credentials cannot."},
    {"code": "scope_forbidden", "status": 403, "surface": "account", "meaning": "The management credential does not hold the scope this route needs, or the route is never available to a management credential.", "recovery": "Stop and tell the person. A new pairing can ask for the scope; the person decides. Do not retry unchanged."},
    {"code": "not_found", "status": 404, "surface": "feed, account, billing, pairing", "meaning": "No match has that record ID, no key or connection on this account has that ID, the pairing code is unknown, expired, already decided against or not addressed to a route, or the path is not a route. A withdrawn match returns its withdrawal, not this.", "recovery": "Check the ID or code. Do not retry unchanged."},
    {"code": "method_not_allowed", "status": 405, "surface": "feed", "meaning": "Feed routes accept GET only.", "recovery": "Use GET."},
    {"code": "ambiguous_record", "status": 409, "surface": "feed", "meaning": "More than one stream has a match with that record ID.", "recovery": "Repeat with ?stream_id=<stream_id> taken from the envelope."},
    {"code": "active_key_limit", "status": 409, "surface": "account", "meaning": "The account already has the maximum number of active keys. Keys issued through pairings count.", "recovery": "Revoke a key you no longer use, then create the new one."},
    {"code": "connection_capacity", "status": 409, "surface": "account", "meaning": "The account already has the maximum number of live agent connections.", "recovery": "The person revokes a connection they no longer use in the account page, then approves again."},
    {"code": "consent_conflict", "status": 409, "surface": "account", "meaning": "The pairing was already decided differently: approved with other permissions, or approved after a denial was sent.", "recovery": "Reload the account page and look at Your connections. Start a new pairing if the first one is not there."},
    {"code": "key_creation_conflict", "status": 409, "surface": "account", "meaning": "The key operation ID or hash conflicts with an existing or revoked key.", "recovery": "Keep pending material; inspect the key by ID. Never change ownership, reactivate it or blindly create another."},
    {"code": "credential_conflict", "status": 409, "surface": "account", "meaning": "A credential hash in the pairing is already in use by another key or connection.", "recovery": "The program starts a new pairing with freshly generated secrets."},
    {"code": "trial_unavailable", "status": 409, "surface": "account", "meaning": "The account's plan cannot start the seven-day trial.", "recovery": "None needed; continue on the current plan."},
    {"code": "builder_already_active", "status": 409, "surface": "account", "meaning": "The trial was requested on an account that already has Builder.", "recovery": "None needed; Builder already has the higher allowance."},
    {"code": "invalid_request", "status": 400, "surface": "feed, account, billing, pairing", "meaning": "The request could not be parsed, or a JSON body has missing or extra fields.", "recovery": "Fix the request. Do not retry unchanged."},
    {"code": "invalid_path", "status": 400, "surface": "feed", "meaning": "The path is not valid UTF-8 text.", "recovery": "Use one of the documented routes."},
    {"code": "invalid_query", "status": 400, "surface": "feed, account", "meaning": "An unknown, repeated or malformed query parameter.", "recovery": "Send only the documented parameters, each once."},
    {"code": "invalid_pagination", "status": 400, "surface": "feed", "meaning": "cursor is neither digits nor the exact word latest, or limit is not digits.", "recovery": "Send digits, for example cursor=0. To start at the head, send cursor=latest once."},
    {"code": "invalid_limit", "status": 400, "surface": "feed", "meaning": "limit is zero or larger than the server page size.", "recovery": "Omit limit to get the server default, or send a smaller number."},
    {"code": "invalid_cursor", "status": 400, "surface": "feed, account", "meaning": "The cursor is out of range or not one the service issued. On a newest-first key listing, the cursor is not a key on this account.", "recovery": "Use the next_cursor from your last response, or 0 to replay from the start."},
    {"code": "invalid_stream", "status": 400, "surface": "feed", "meaning": "stream_id is not 1-64 letters, digits, underscores or hyphens.", "recovery": "Copy stream_id exactly from the envelope."},
    {"code": "conflicting_market", "status": 400, "surface": "feed", "meaning": "The market in the path and the market_id parameter disagree.", "recovery": "Send one or the other."},
    {"code": "invalid_market_id", "status": 400, "surface": "feed", "meaning": "A market filter is not 0x followed by 64 lower-case hexadecimal characters.", "recovery": "Send the market's condition ID in that form, not a slug, event ID or token ID."},
    {"code": "invalid_content_length", "status": 400, "surface": "feed, account, billing, pairing", "meaning": "The Content-Length header is malformed.", "recovery": "Fix the client; GET requests need no body."},
    {"code": "unexpected_body", "status": 400, "surface": "feed, account, billing", "meaning": "A body was sent to a route that takes none.", "recovery": "Remove the body."},
    {"code": "invalid_body", "status": 400, "surface": "account, pairing", "meaning": "The body is shorter than Content-Length or could not be read.", "recovery": "Send the documented JSON object with a correct Content-Length."},
    {"code": "invalid_key_name", "status": 400, "surface": "account, pairing", "meaning": "The key or connection name is empty, longer than 64 characters or contains control characters; a pairing name must also be printable ASCII.", "recovery": "Choose a 1-64 character name."},
    {"code": "invalid_scopes", "status": 400, "surface": "account, pairing", "meaning": "scopes is not a list of distinct known scopes that includes news:read, or the approved scopes are not a subset of the requested ones.", "recovery": "Send scopes from the documented list, each once, always with news:read."},
    {"code": "invalid_credential_hash", "status": 400, "surface": "pairing", "meaning": "A credential hash is not 64 lower-case hexadecimal characters, the two hashes are equal, or management_token_hash does not match the scopes.", "recovery": "Send SHA-256 hashes of two different secrets; send management_token_hash as null when the only scope is news:read."},
    {"code": "authorization_pending", "status": 400, "surface": "pairing", "meaning": "Nobody has decided the pairing yet. Not a failure.", "recovery": "Wait interval seconds and poll again, until expires_in has passed."},
    {"code": "access_denied", "status": 400, "surface": "account, pairing", "meaning": "The person denied the pairing, or its connection was revoked before the receipt was collected. Definitive: nothing is active.", "recovery": "Stop. Discard the pending secrets. Start a new pairing only if the person asks."},
    {"code": "expired_token", "status": 400, "surface": "pairing", "meaning": "The device code is unknown or its window has ended. Not proof that the pairing was never approved.", "recovery": "Stop polling. If a pairing was started with this code, keep the pending secrets, report that delivery is unknown and ask the person to check Your connections in the account page and revoke the named connection if unwanted."},
    {"code": "content_length_required", "status": 411, "surface": "account, pairing", "meaning": "A write was sent without Content-Length.", "recovery": "Send Content-Length."},
    {"code": "request_too_large", "status": 413, "surface": "feed, account, billing, pairing", "meaning": "The request body exceeds the server limit.", "recovery": "Feed reads have no body; remove it."},
    {"code": "request_target_too_large", "status": 414, "surface": "feed, account, pairing", "meaning": "The URL is too long.", "recovery": "Shorten the request; send only documented parameters."},
    {"code": "json_required", "status": 415, "surface": "account, pairing", "meaning": "A write body was not sent as application/json.", "recovery": "Set Content-Type: application/json."},
    {"code": "account_quota_exceeded", "status": 429, "surface": "feed", "meaning": "The account has used its news responses for this UTC day.", "recovery": "Stop polling and tell the person. The daily news allowance is used and resets at 00:00 UTC; reset_at, Retry-After and X-RateLimit-Reset give the time and upgrade_url is where the person can change plan. Poll less often or change plan. Do not sleep until the reset and do not make another key: keys share one allowance."},
    {"code": "account_data_limit", "status": 429, "surface": "feed", "meaning": "The account has used its response-byte allowance for this UTC day.", "recovery": "Stop and tell the person, as for account_quota_exceeded. Afterwards use a smaller limit and avoid replaying from zero."},
    {"code": "coverage_quota_exceeded", "status": 429, "surface": "feed", "meaning": "The separate allowance for GET /v1/coverage is used up.", "recovery": "Stop reading coverage and report it; Retry-After gives the reset. News reads are not affected. Read coverage less often than news."},
    {"code": "usage_quota_exceeded", "status": 429, "surface": "feed", "meaning": "The separate allowance for GET /v1/usage is used up.", "recovery": "Stop reading usage and report it; Retry-After gives the reset. News reads are not affected. The X-RateLimit headers on news responses carry the same numbers."},
    {"code": "management_quota_exceeded", "status": 429, "surface": "account", "meaning": "Too many account operations in this window. Revoking a key or connection from the account page is not held back by this.", "recovery": "Stop and tell the person; Retry-After gives the reset. Do not retry in a loop."},
    {"code": "agent_quota_exceeded", "status": 429, "surface": "account", "meaning": "This connection, or all connections together, made too many account requests in this window. Separate from the person's own account-page allowance.", "recovery": "Stop and tell the person; Retry-After gives the reset. Do not retry in a loop."},
    {"code": "approval_limited", "status": 429, "surface": "account", "meaning": "Too many pairing codes were tried on this account in a short time.", "recovery": "Stop and tell the person; Retry-After gives the wait. Check the code shown by the program before trying again."},
    {"code": "pairing_capacity", "status": 429, "surface": "pairing", "meaning": "Too many pairings were started from this network, or across the service, in this window.", "recovery": "Stop and tell the person; Retry-After gives the wait. Do not start pairings in a loop."},
    {"code": "billing_quota_exceeded", "status": 429, "surface": "billing", "meaning": "Too many billing operations in this window.", "recovery": "Stop and tell the person; Retry-After gives the reset. Do not retry in a loop."},
    {"code": "burst_limited", "status": 429, "surface": "feed, account, billing, pairing", "meaning": "Too many requests from this network address in a short window. Not charged against the daily allowance.", "recovery": "If Retry-After is short, wait that long and retry a bounded number of times, then slow down. If it is not short, stop and report it."},
    {"code": "burst_capacity", "status": 429, "surface": "feed, account, billing, pairing", "meaning": "The short-window limiter is tracking too many addresses to admit a new one.", "recovery": "If Retry-After is short, wait that long and retry a bounded number of times. Otherwise stop and report it."},
    {"code": "server_capacity", "status": 429, "surface": "feed, account, billing", "meaning": "The whole service has reached its own allowance for this window. Not specific to your account.", "recovery": "Not specific to your account, and another key does not help. Retry only if Retry-After is short; otherwise stop and report it."},
    {"code": "billing_subscription_exists", "status": 409, "surface": "billing", "meaning": "Checkout was requested for an account that already has a subscription or paid time remaining.", "recovery": "Open the billing portal from the account page instead."},
    {"code": "billing_checkout_needs_recovery", "status": 409, "surface": "billing", "meaning": "An earlier checkout attempt has an unknown outcome and is too old to resume automatically.", "recovery": "Do not start another. Email access@throughline.markets."},
    {"code": "billing_checkout_needs_refresh", "status": 409, "surface": "billing", "meaning": "The saved checkout link has expired or was never issued.", "recovery": "Reload the account page and start checkout again."},
    {"code": "billing_customer_unavailable", "status": 409, "surface": "billing", "meaning": "The billing portal was requested for an account with no billing customer yet.", "recovery": "Start checkout first."},
    {"code": "billing_attempt_unknown", "status": 409, "surface": "billing", "meaning": "The checkout attempt being resumed does not exist.", "recovery": "Reload the account page and start checkout again."},
    {"code": "billing_provider_unavailable", "status": 503, "surface": "billing", "meaning": "The payment provider did not give a usable answer.", "recovery": "Retry later. No charge follows from this response alone."},
    {"code": "billing_payment_conflict", "status": 503, "surface": "billing", "meaning": "A payment record disagrees with one already stored.", "recovery": "Stop. Email access@throughline.markets."},
    {"code": "service_busy", "status": 503, "surface": "feed, account, billing, pairing", "meaning": "All request slots are in use.", "recovery": "Wait Retry-After seconds (1) and retry a bounded number of times."},
    {"code": "service_unavailable", "status": 503, "surface": "feed, account, billing, pairing", "meaning": "Storage was unavailable for this request.", "recovery": "Retry a bounded number of times with short waits. Keep your cursor; nothing was consumed. For a pairing poll, keep the pending secrets and poll again."},
    {"code": "response_too_large", "status": 503, "surface": "feed, account, billing", "meaning": "The response would exceed the server's size limit.", "recovery": "On a feed read, repeat with a smaller limit. Elsewhere, retry later."},
    {"code": "internal_error", "status": 500, "surface": "feed, account, billing, pairing", "meaning": "An unexpected failure. No detail is returned by design.", "recovery": "Do not retry automatically. Keep your cursor and let the next scheduled poll try again. If it persists, email access@throughline.markets with the request_id, the time and the route."}
  ],
  "error_scope": "The errors list covers the customer-callable feed, account, billing and pairing routes in the routes list. Codes are listed per route family (feed, account, billing, pairing); a family's codes are shared possibilities, and not every code can arise on every operation in it. Provider webhook deliveries are outside this list and outside the published schema and OpenAPI file.",
  "provider_only_errors": {
    "note": "Returned only to the sign-in and payment providers' webhook deliveries, which customers never call. Provider-webhook-only: not part of the customer error enum, schema or OpenAPI file.",
    "codes": ["invalid_webhook", "invalid_stripe_event", "billing_event_conflict"],
    "detail": [
      {"code": "invalid_webhook", "status": 400, "sender": "sign-in provider", "meaning": "A sign-in provider delivery was not a usable event."},
      {"code": "invalid_stripe_event", "status": 400, "sender": "payment provider", "meaning": "A payment provider delivery failed signature, freshness or shape checks."},
      {"code": "billing_event_conflict", "status": 400, "sender": "payment provider", "meaning": "A payment provider delivery reused an event identifier with different content."}
    ]
  }
}
