@0xinsider/sdk 0.14.0-bootstrap.0

package/dist/errors.js

@@ -0,0 +1,700 @@
+/**
+ * Typed error hierarchy for the 0xinsider API V1 error envelope.
+ *
+ * The V1 contract returns a stable error shape on every non-2xx response
+ * (`web/public/api/v1/openapi.json` -> components.schemas.ApiError):
+ *
+ *   {
+ *     "object": "error",
+ *     "error": { "code": <ApiErrorCode>, "message": string, "doc_url"?, "param"? },
+ *     "meta":  { "request_id": string, "cached": boolean, "cost": number, ... }
+ *   }
+ *
+ * Some upstream/proxy failures return a flat body `{ code, message }` without
+ * the `object: "error"` wrapper; both shapes are normalized here.
+ *
+ * The canonical `code` set is the `ApiError.error.code` enum in the OpenAPI
+ * spec. The client maps each error to the most specific subclass -- dispatching on `reason` first (it is strictly more specific), then `code` so callers can
+ * `instanceof` the specific failure, and falls back to the base
+ * `OxinsiderApiError` for unknown codes or non-JSON bodies.
+ */
+/**
+ * Canonical error codes the API can return. Source of truth:
+ * `components.schemas.ApiError.properties.error.properties.code.enum`.
+ */
+export const API_ERROR_CODES = [
+    "bad_request",
+    "invalid_api_key",
+    "subscription_required",
+    "forbidden",
+    "not_found",
+    "account_locked",
+    "rate_limited",
+    "rate_limit_unavailable",
+    "internal_error",
+    // 403 (#13689): an OAuth token that lacks the scope this route needs.
+    "insufficient_scope",
+    // 408 (#16146): the handler did not answer inside the server's 30-second
+    // timeout. Dispatched to ServerTimeoutError below.
+    "request_timeout",
+];
+/**
+ * The specific, actionable cause behind a `code`. Source of truth:
+ * `components.schemas.ApiError.properties.error.properties.reason.enum`.
+ *
+ * Additive (#7209): `code` keeps its published values, so this never changes what
+ * an existing `code` means. It tells you what to DO, where the code alone could
+ * not: `pick_not_released` is "not YET" (sleep until `retryAt`), not "does not
+ * exist"; `unknown_endpoint` is a wrong PATH (do not retry); `trader_not_tracked`
+ * is a wallet we do not capture (stop asking for it); `cursor_expired` means
+ * re-request page 1; `read_model_warming` is endpoint-local unavailability,
+ * not rate limiting. Retry only that route after the supplied interval; do not
+ * infer dependency health from the reason.
+ */
+export const API_ERROR_REASONS = [
+    "cursor_expired",
+    "unknown_endpoint",
+    "pick_not_released",
+    "trader_not_tracked",
+    "read_model_warming",
+    "database_unavailable",
+    "request_accounting_unavailable",
+    // 409 conflict causes (code `bad_request` at HTTP 409): the same mutation is
+    // still running / a webhook endpoint is mid-delivery. Dispatched to
+    // IdempotencyInProgressError / WebhookDeliveryInProgressError below, both
+    // refining BadRequestError to match the wire code.
+    "idempotency_in_progress",
+    "webhook_delivery_in_progress",
+    // Staged webhook rotation state: prepare before activate, and retire the
+    // bounded overlap before starting another staged rotation.
+    "webhook_secret_rotation_not_prepared",
+    "webhook_secret_rotation_overlap_active",
+    // 401 `invalid_api_key` refinement (#13959): a sandbox key sent to the live
+    // API. Dispatched to SandboxApiKeyError below.
+    "sandbox_api_key",
+    // 401 `invalid_api_key` refinement (#14123): the key was sent as a `?token=`
+    // query parameter, which no route reads. Dispatched to ApiKeyInQueryError.
+    "api_key_in_query",
+    // 402 `subscription_required` refinement (#14283): the account's Pro
+    // subscription has lapsed. Permanent until a person reactivates; the
+    // message names the URL. Carried on SubscriptionRequiredError.reason.
+    "subscription_inactive",
+    // 429 `rate_limited` refinement (#16111): the account has used the requests
+    // Pro includes for the UTC calendar month. `retry_at` is the first of next
+    // month; pay as you go is turned on at https://0xinsider.com/developers.
+    "monthly_quota_exceeded",
+    // 400 `bad_request` refinements (#16146): the request never reached a
+    // handler because a query parameter, a path segment or the JSON body did
+    // not parse or did not fit the route's schema; `param` names the field
+    // when the server named one. Fix the request; never retry it as sent.
+    "invalid_query",
+    // 400 `bad_request` refinement (#16189): strict query validation rejected a
+    // name the operation does not publish before the handler ran.
+    "unknown_query_parameter",
+    "invalid_path",
+    "invalid_body",
+    // 415, 413 and 405 under `bad_request` (#16146): send the body as
+    // `Content-Type: application/json`; keep it under 1 MiB; use a method the
+    // path serves (`Allow` names them). All three arrive as BadRequestError
+    // with `reason` set.
+    "unsupported_media_type",
+    "payload_too_large",
+    "method_not_allowed",
+    // 429 `rate_limited` refinements (#16380): the per-address budget shared by
+    // every caller behind one IP (`ip_rate_limited`; the RateLimit-* headers
+    // describe that bucket, not the key's), and an address cooldown after
+    // sustained over-limit traffic (`ip_throttled`; Retry-After is minutes to
+    // days and an earlier retry extends it). Both arrive as RateLimitedError
+    // with `reason` set; sleep `retryAfterSeconds` either way.
+    "ip_rate_limited",
+    "ip_throttled",
+    // 410 `not_found` refinement (#16181): the export job finished but its
+    // retention window has passed and the file is retired. Arrives as
+    // NotFoundError with `status` 410 and `reason` set; submit a new export,
+    // polling or retrying the download cannot succeed.
+    "export_expired",
+    // 409 `bad_request` refinement (#16964): an opt-in trader freshness ceiling
+    // could not be met by the stored body. The response carries the requested
+    // ceiling and the measured clock when one exists; retrying does not refresh it.
+    "freshness_ceiling_unsatisfied",
+];
+/**
+ * The SDK's deadline (`timeoutMs`) expired during the request, body read, or
+ * retry backoff. Caller cancellation preserves the caller's exact reason.
+ * Not an `OxinsiderApiError`: there is no status, body, or request id.
+ */
+export class RequestTimeoutError extends Error {
+    operationId;
+    timeoutMs;
+    constructor(operationId, timeoutMs) {
+        super(`0xinsider API ${operationId} did not answer within ${String(timeoutMs)} ms`);
+        this.name = "RequestTimeoutError";
+        this.operationId = operationId;
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * An owned JSON/text response failed while its body was being read.
+ * Headers may have arrived successfully; no body, URL or credential is copied.
+ * The native read failure is retained as cause. Client deadlines and caller
+ * abort reasons take precedence, and this failure does not trigger a retry.
+ */
+export class ResponseBodyReadError extends Error {
+    responseStatus;
+    phase = "response_body";
+    constructor(responseStatus, cause) {
+        super("0xinsider API response body could not be read", { cause });
+        this.responseStatus = responseStatus;
+        this.name = "ResponseBodyReadError";
+    }
+}
+/**
+ * The export object was read, but its streamed bytes did not match the
+ * immutable manifest returned by the status route. The partial file must be
+ * discarded before requesting a fresh download.
+ */
+export class ExportIntegrityError extends Error {
+    jobId;
+    expectedSha256;
+    actualSha256;
+    expectedSizeBytes;
+    actualSizeBytes;
+    cause;
+    constructor(jobId, expectedSha256, actualSha256, expectedSizeBytes, actualSizeBytes, cause) {
+        const message = actualSha256 === null
+            ? `Export job ${String(jobId)} could not be verified: the download ended before its SHA-256 could be checked after ${String(actualSizeBytes)} of ${String(expectedSizeBytes)} bytes. Discard the partial file and request a fresh download.`
+            : `Export job ${String(jobId)} failed integrity verification: expected ${String(expectedSizeBytes)} bytes with SHA-256 ${expectedSha256}, received ${String(actualSizeBytes)} bytes with SHA-256 ${actualSha256}. Discard the partial file and request a fresh download.`;
+        super(message);
+        this.name = "ExportIntegrityError";
+        this.jobId = jobId;
+        this.expectedSha256 = expectedSha256;
+        this.actualSha256 = actualSha256;
+        this.expectedSizeBytes = expectedSizeBytes;
+        this.actualSizeBytes = actualSizeBytes;
+        this.cause = cause;
+    }
+}
+/** `value` when it is one of `API_ERROR_REASONS`, otherwise `null` (#16547). */
+function knownApiErrorReason(value) {
+    return typeof value === "string" &&
+        API_ERROR_REASONS.includes(value)
+        ? value
+        : null;
+}
+function extractFreshnessFailure(error) {
+    const value = error?.freshness;
+    return value && typeof value === "object" ? value : null;
+}
+/**
+ * Base class for every error thrown by the SDK on a non-2xx API response.
+ * Subclasses below specialize by documented `code`.
+ */
+export class OxinsiderApiError extends Error {
+    /** HTTP status code of the failing response. */
+    status;
+    /** Documented error code, when the body carried one. */
+    code;
+    /**
+     * The specific, actionable cause behind `code`, or `null` when the response carried
+     * no reason the SDK recognizes (#7209).
+     *
+     * Declared on the BASE class, not only on the five reason subclasses, so the thing an
+     * SDK user actually writes type-checks:
+     *
+     *   catch (e) { if (e instanceof OxinsiderApiError && e.reason === "pick_not_released") ... }
+     *
+     * With `reason` living only on the subclasses, that read was a type error, and the only
+     * way to branch on the cause was an `instanceof` ladder over all five -- which defeats
+     * the point of shipping a reason at all. The subclasses narrow this to their own literal.
+     *
+     * The raw wire value always stays on `error.reason`, so a reason NEWER than this SDK is
+     * never destroyed -- it is simply not typed yet, and reads as `null` here.
+     *
+     * Read from the wire for EVERY class (#16547): a `SubscriptionRequiredError` carries
+     * `subscription_inactive`, a `RateLimitedError` carries `monthly_quota_exceeded`,
+     * `ip_rate_limited` or `ip_throttled`, and a `BadRequestError` carries `invalid_body`,
+     * `payload_too_large` and the rest. Until then only the subclasses that pin a literal
+     * carried a value and every other known reason read `null`.
+     */
+    reason;
+    /**
+     * When retrying can first succeed, or `null` when the error is terminal.
+     *
+     * On the BASE class for exactly the reason `reason` is, and the backend says so in its
+     * own contract (`ApiErrorBody::retry_at`): the field is "generic on purpose ... so
+     * clients key on ONE field across the whole API rather than a per-endpoint zoo". With
+     * `retryAt` living only on the three retryable subclasses,
+     *
+     *   catch (e) { if (e instanceof OxinsiderApiError && e.retryAt) scheduleRetry(e.retryAt) }
+     *
+     * was a type error -- the same defect the `reason` hoist above exists to fix, left in
+     * place one field over.
+     *
+     * Parsed from the wire on every error, so it is present whenever the API sends it and
+     * `null` when it does not. A terminal error (`cursor_expired`, `trader_not_tracked`)
+     * has no `retry_at`, and `null` is the honest answer: do not retry this.
+     *
+     * DO NOT BLOCK A WORKER THREAD ON IT. On `pick_not_released` this can be 13-14 hours
+     * out (a full day on a skipped day). Schedule the retry; do not sleep.
+     */
+    retryAt;
+    /** Parsed `error` object (`{ code, message, doc_url?, param? }`), or null. */
+    error;
+    /** Response `meta` (`request_id`, `cost`, ...), or null. */
+    meta;
+    /** Body `meta.request_id`, or the received `X-Request-ID` when absent. */
+    requestId;
+    /** Parsed `Retry-After` guidance, independent of whether this request can be retried. */
+    retryAfterSeconds;
+    /** Raw, unparsed body for debugging. */
+    body;
+    constructor(status, body, transport = {}) {
+        const error = extractApiErrorBody(body);
+        const meta = extractApiErrorMeta(body);
+        const message = error?.message ??
+            `0xinsider API request failed with status ${String(status)}`;
+        super(message);
+        this.name = "OxinsiderApiError";
+        this.status = status;
+        this.code = error?.code;
+        this.reason = knownApiErrorReason(error?.reason);
+        this.error = error;
+        this.meta = meta;
+        const headerRequestId = transport.requestId;
+        this.requestId = meta?.request_id ??
+            (headerRequestId?.trim() ? headerRequestId : undefined);
+        this.retryAfterSeconds = transport.retryAfterSeconds ?? null;
+        this.body = body;
+        // Parsed once, here, for EVERY error. The retryable subclasses no longer parse it
+        // themselves -- two parsers for one wire field is how they drift.
+        this.retryAt = parseRetryAt(body);
+    }
+}
+/** 400 - the request was malformed; see `param` for the offending field. */
+export class BadRequestError extends OxinsiderApiError {
+    code = "bad_request";
+    constructor(status, body, transport = {}) {
+        super(status, body, transport);
+        this.name = "BadRequestError";
+    }
+}
+/**
+ * 409 `reason: freshness_ceiling_unsatisfied` - a trader response did not
+ * satisfy the caller's opt-in whole-response age ceiling. The server does not
+ * refresh or bypass its normal read, so the caller may use the details to decide
+ * whether to accept the body or try again later.
+ */
+export class FreshnessCeilingUnsatisfiedError extends BadRequestError {
+    reason = "freshness_ceiling_unsatisfied";
+    freshness;
+    constructor(status, body, transport = {}) {
+        super(status, body, transport);
+        this.name = "FreshnessCeilingUnsatisfiedError";
+        this.freshness = extractFreshnessFailure(this.error);
+    }
+}
+/**
+ * 400 `reason: unknown_query_parameter` - strict validation rejected a query
+ * name the operation does not publish. Remove or correct the name, or leave
+ * `strictQuery` unset while migrating a caller.
+ */
+export class UnknownQueryParameterError extends BadRequestError {
+    reason = "unknown_query_parameter";
+    constructor(status, body, transport = {}) {
+        super(status, body, transport);
+        this.name = "UnknownQueryParameterError";
+    }
+}
+/** 401 - the `oxi_sk_*` API key is missing, malformed, or revoked. */
+export class InvalidApiKeyError extends OxinsiderApiError {
+    code = "invalid_api_key";
+    constructor(status, body, transport = {}) {
+        super(status, body, transport);
+        this.name = "InvalidApiKeyError";
+    }
+}
+/**
+ * 401 `reason: sandbox_api_key` - the credential is a sandbox key (`oxi_sk_test_`)
+ * from `POST /api/v1/agents/register` (#13959). Only the sandbox server accepts
+ * it: call `https://0xinsider.com/sandbox/api/v1` with it, or use a live key or
+ * OAuth access token. Retrying here will not help.
+ */
+export class SandboxApiKeyError extends InvalidApiKeyError {
+    reason = "sandbox_api_key";
+    constructor(status, body, transport = {}) {
+        super(status, body, transport);
+        this.name = "SandboxApiKeyError";
+    }
+}
+/**
+ * 401 `reason: api_key_in_query` - the key was sent as a `?token=` query
+ * parameter (#14123). No route reads a key from the URL, so the key itself was
+ * not checked: resend it as `Authorization: Bearer`. This client always sends
+ * the header, so seeing this means a URL was built by hand.
+ */
+export class ApiKeyInQueryError extends InvalidApiKeyError {
+    reason = "api_key_in_query";
+    constructor(status, body, transport = {}) {
+        super(status, body, transport);
+        this.name = "ApiKeyInQueryError";
+    }
+}
+/**
+ * 402 - the key is valid but the account has no active Pro subscription.
+ *
+ * Permanent until a person reactivates (`reason: subscription_inactive`,
+ * #14283): there is no `Retry-After`, and a retry on a schedule never clears
+ * it. Stop the loop and surface `reactivationUrl` to your own user. The key
+ * and its settings are unchanged and work again the moment Pro is active;
+ * the owner is emailed once per lapse.
+ */
+export class SubscriptionRequiredError extends OxinsiderApiError {
+    code = "subscription_required";
+    /** Where the account reactivates Pro. */
+    reactivationUrl = "https://0xinsider.com/billing";
+    constructor(status, body, transport = {}) {
+        super(status, body, transport);
+        this.name = "SubscriptionRequiredError";
+    }
+}
+/** 403 - the key is authenticated but not allowed to access this resource. */
+export class ForbiddenError extends OxinsiderApiError {
+    code = "forbidden";
+    constructor(status, body, transport = {}) {
+        super(status, body, transport);
+        this.name = "ForbiddenError";
+    }
+}
+/** 404 - the requested resource does not exist. */
+export class NotFoundError extends OxinsiderApiError {
+    code = "not_found";
+    constructor(status, body, transport = {}) {
+        super(status, body, transport);
+        this.name = "NotFoundError";
+    }
+}
+/** 403 - the account is locked; contact support. */
+export class AccountLockedError extends OxinsiderApiError {
+    code = "account_locked";
+    constructor(status, body, transport = {}) {
+        super(status, body, transport);
+        this.name = "AccountLockedError";
+    }
+}
+/**
+ * 429 - the per-key rate limit was exceeded. `retryAfterSeconds` is read from
+ * the standard `Retry-After` response header when present.
+ */
+export class RateLimitedError extends OxinsiderApiError {
+    code = "rate_limited";
+    constructor(status, body, retryAfterSeconds, transport = {}) {
+        super(status, body, { ...transport, retryAfterSeconds });
+        this.name = "RateLimitedError";
+    }
+}
+/**
+ * 408 `request_timeout` (#16146) - the server did not finish the request
+ * inside its 30-second timeout. Distinct from `RequestTimeoutError`, which is
+ * this client's own deadline with no response at all.
+ *
+ * `retryAfterSeconds` is set only on a safe method (GET, HEAD): the server
+ * gives a mutation no hint, because it may have completed. Check its state
+ * before repeating it, and reuse its Idempotency-Key.
+ */
+export class ServerTimeoutError extends OxinsiderApiError {
+    code = "request_timeout";
+    constructor(status, body, retryAfterSeconds, transport = {}) {
+        super(status, body, { ...transport, retryAfterSeconds });
+        this.name = "ServerTimeoutError";
+    }
+}
+/** 503 - the rate-limit/admission backend was briefly unavailable; retry. */
+export class RateLimitUnavailableError extends OxinsiderApiError {
+    code = "rate_limit_unavailable";
+    constructor(status, body, retryAfterSeconds, transport = {}) {
+        super(status, body, { ...transport, retryAfterSeconds });
+        this.name = "RateLimitUnavailableError";
+    }
+}
+/**
+ * 404 `reason: pick_not_released` - no Pick of the Day is published for the
+ * current product day (#7209).
+ *
+ * This is NOT "the endpoint is broken" and NOT "the resource does not exist".
+ * Each selected pick releases about an hour before its own provider kickoff, inside
+ * the daily operating window, 11:00 UTC to 23:00 America/New_York (#7226, #7709,
+ * #16207) -- there is no fixed publish clock time. The product day rolls at midnight America/New_York, so the
+ * endpoint legitimately 404s from that roll until the day's release (a span that
+ * varies with the pick's kickoff), and for the full product day on a skipped day.
+ *
+ * DO NOT POLL. Sleep for `retryAfterSeconds` (or until `retryAt`) and request
+ * once. Blind polling through this window was 91.8% of all logged v1 API errors.
+ */
+export class PickNotReleasedError extends NotFoundError {
+    reason = "pick_not_released";
+    constructor(status, body, retryAfterSeconds, transport = {}) {
+        super(status, body, { ...transport, retryAfterSeconds });
+        this.name = "PickNotReleasedError";
+    }
+}
+/**
+ * 503 `reason: read_model_warming` - endpoint-local read-model unavailability (#7209).
+ *
+ * This is not rate limiting. Retry only this route after the supplied interval;
+ * the exact cause is endpoint-specific, so do not infer dependency health from
+ * this reason.
+ */
+export class ReadModelWarmingError extends RateLimitUnavailableError {
+    reason = "read_model_warming";
+    constructor(status, body, retryAfterSeconds, transport = {}) {
+        super(status, body, retryAfterSeconds, transport);
+        this.name = "ReadModelWarmingError";
+    }
+}
+/**
+ * 503 `reason: database_unavailable` - the API's database or its connection
+ * pool is temporarily unreachable (#10737). A connection-class failure, not a
+ * query fault, and not rate limiting: back off for `retryAfterSeconds`, then
+ * retry the same request.
+ */
+export class DatabaseUnavailableError extends RateLimitUnavailableError {
+    reason = "database_unavailable";
+    constructor(status, body, retryAfterSeconds, transport = {}) {
+        super(status, body, retryAfterSeconds, transport);
+        this.name = "DatabaseUnavailableError";
+    }
+}
+/** 503 - accounting capacity was unavailable before the handler ran. */
+export class RequestAccountingUnavailableError extends RateLimitUnavailableError {
+    reason = "request_accounting_unavailable";
+    constructor(status, body, retryAfterSeconds, transport = {}) {
+        super(status, body, retryAfterSeconds, transport);
+        this.name = "RequestAccountingUnavailableError";
+    }
+}
+/**
+ * 400 `reason: cursor_expired` - the pagination cursor was invalidated by an
+ * upstream data change (#7209). Recovery is mechanical: re-request the first page
+ * and continue. This is NOT a bad parameter -- do not stop retrying.
+ */
+export class CursorExpiredError extends BadRequestError {
+    reason = "cursor_expired";
+    constructor(status, body, transport = {}) {
+        super(status, body, transport);
+        this.name = "CursorExpiredError";
+    }
+}
+/**
+ * 409 `reason: idempotency_in_progress` - the same idempotent mutation is still
+ * running. Retain the exact `Idempotency-Key` and body and retry shortly; do NOT
+ * mint a new mutation. The wire carries code `bad_request` at HTTP 409, so this
+ * refines `BadRequestError` -- a consumer catching `BadRequestError` still matches.
+ */
+export class IdempotencyInProgressError extends BadRequestError {
+    reason = "idempotency_in_progress";
+    constructor(status, body, transport = {}) {
+        super(status, body, transport);
+        this.name = "IdempotencyInProgressError";
+    }
+}
+/**
+ * 409 `reason: webhook_delivery_in_progress` - a webhook endpoint's URL and
+ * signing secret are frozen while a delivery is in flight. Retry the
+ * configuration change after that delivery completes. The wire carries code
+ * `bad_request` at HTTP 409, so this refines `BadRequestError`.
+ */
+export class WebhookDeliveryInProgressError extends BadRequestError {
+    reason = "webhook_delivery_in_progress";
+    constructor(status, body, transport = {}) {
+        super(status, body, transport);
+        this.name = "WebhookDeliveryInProgressError";
+    }
+}
+/**
+ * 404 `reason: unknown_endpoint` - the PATH is not a route on this API (#7209).
+ * Read `GET /api/v1` for the route index. Retrying will not help.
+ */
+export class UnknownEndpointError extends NotFoundError {
+    reason = "unknown_endpoint";
+    constructor(status, body, transport = {}) {
+        super(status, body, transport);
+        this.name = "UnknownEndpointError";
+    }
+}
+/**
+ * 404 `reason: trader_not_tracked` - the wallet is real and the URL is right, but
+ * the trader is outside the HOT/WARM sync tiers so we do not capture this data
+ * for them (#7209). Stop asking for this wallet; do not hunt for a different URL.
+ */
+export class TraderNotTrackedError extends NotFoundError {
+    reason = "trader_not_tracked";
+    constructor(status, body, transport = {}) {
+        super(status, body, transport);
+        this.name = "TraderNotTrackedError";
+    }
+}
+/** Parse the RFC3339 `error.retry_at` off an error envelope, if present. */
+function parseRetryAt(body) {
+    const raw = extractApiErrorBody(body)?.retry_at;
+    if (typeof raw !== "string")
+        return null;
+    const parsed = new Date(raw);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+/**
+ * A 2xx response whose body does not match the contract this client relies
+ * on (#16246): a list operation answering without a list envelope, or with a
+ * `has_more` that is not a boolean or a `next_cursor` that is not a string.
+ * `code` is `invalid_response`, a client-side code that the API never sends;
+ * `received` is the body as parsed. Not retried: the same request would
+ * return the same body. Report it with `requestId` when the body carried one.
+ */
+export class InvalidResponseError extends OxinsiderApiError {
+    code = "invalid_response";
+    /** The response body as received, for diagnosis. */
+    received;
+    constructor(status, message, received) {
+        super(status, {
+            object: "error",
+            error: { code: "invalid_response", message },
+            ...(typeof received === "object" &&
+                received !== null &&
+                "meta" in received
+                ? { meta: received.meta }
+                : {}),
+        });
+        this.name = "InvalidResponseError";
+        this.received = received;
+    }
+}
+/** 5xx - an unexpected server-side error; retry only when the request is safe to replay. */
+export class InternalServerError extends OxinsiderApiError {
+    code = "internal_error";
+    constructor(status, body, transport = {}) {
+        super(status, body, transport);
+        this.name = "InternalServerError";
+    }
+}
+/**
+ * Construct the most specific `OxinsiderApiError` subclass for a failed
+ * response. Dispatch is by `error.reason` FIRST -- strictly more specific than the code,
+ * because the reason names the CAUSE where the code names only the class -- then by
+ * `error.code`, then a status-code heuristic, falling back to the base class for anything
+ * unrecognized so an unknown code is never silently dropped.
+ */
+export function errorFromResponse(status, body, retryAfterSeconds = null, transport = {}) {
+    const metadata = { ...transport, retryAfterSeconds };
+    const parsed = extractApiErrorBody(body);
+    const code = parsed?.code;
+    // `reason` first: it is strictly more specific than `code` (#7209), and it is
+    // what carries the actionable distinction -- "not yet" vs "does not exist",
+    // "warming" vs "rate limiter down". Falling through to `code` here is what made
+    // the SDK re-assert the very lie the backend removed.
+    switch (parsed?.reason) {
+        case "freshness_ceiling_unsatisfied":
+            return new FreshnessCeilingUnsatisfiedError(status, body, metadata);
+        case "pick_not_released":
+            return new PickNotReleasedError(status, body, retryAfterSeconds, metadata);
+        case "read_model_warming":
+            return new ReadModelWarmingError(status, body, retryAfterSeconds, metadata);
+        case "request_accounting_unavailable":
+            return new RequestAccountingUnavailableError(status, body, retryAfterSeconds, metadata);
+        case "database_unavailable":
+            return new DatabaseUnavailableError(status, body, retryAfterSeconds, metadata);
+        case "cursor_expired":
+            return new CursorExpiredError(status, body, metadata);
+        case "unknown_endpoint":
+            return new UnknownEndpointError(status, body, metadata);
+        case "trader_not_tracked":
+            return new TraderNotTrackedError(status, body, metadata);
+        case "idempotency_in_progress":
+            return new IdempotencyInProgressError(status, body, metadata);
+        case "webhook_delivery_in_progress":
+            return new WebhookDeliveryInProgressError(status, body, metadata);
+        case "sandbox_api_key":
+            return new SandboxApiKeyError(status, body, metadata);
+        case "api_key_in_query":
+            return new ApiKeyInQueryError(status, body, metadata);
+        case "unknown_query_parameter":
+            return new UnknownQueryParameterError(status, body, metadata);
+        default:
+            break;
+    }
+    switch (code) {
+        case "bad_request":
+            return new BadRequestError(status, body, metadata);
+        case "invalid_api_key":
+            return new InvalidApiKeyError(status, body, metadata);
+        case "subscription_required":
+            return new SubscriptionRequiredError(status, body, metadata);
+        case "forbidden":
+            return new ForbiddenError(status, body, metadata);
+        case "not_found":
+            return new NotFoundError(status, body, metadata);
+        case "account_locked":
+            return new AccountLockedError(status, body, metadata);
+        case "rate_limited":
+            return new RateLimitedError(status, body, retryAfterSeconds, metadata);
+        case "rate_limit_unavailable":
+            return new RateLimitUnavailableError(status, body, retryAfterSeconds, metadata);
+        case "request_timeout":
+            return new ServerTimeoutError(status, body, retryAfterSeconds, metadata);
+        case "internal_error":
+            return new InternalServerError(status, body, metadata);
+        default:
+            break;
+    }
+    // No (or unknown) error code: dispatch on the HTTP status so common
+    // failures still arrive as the expected subclass.
+    switch (status) {
+        case 400:
+            return new BadRequestError(status, body, metadata);
+        case 401:
+            return new InvalidApiKeyError(status, body, metadata);
+        case 402:
+            return new SubscriptionRequiredError(status, body, metadata);
+        case 404:
+            return new NotFoundError(status, body, metadata);
+        case 408:
+            return new ServerTimeoutError(status, body, retryAfterSeconds, metadata);
+        case 429:
+            return new RateLimitedError(status, body, retryAfterSeconds, metadata);
+        case 503:
+            return new RateLimitUnavailableError(status, body, retryAfterSeconds, metadata);
+        default:
+            if (status >= 500) {
+                return new InternalServerError(status, body, metadata);
+            }
+            return new OxinsiderApiError(status, body, metadata);
+    }
+}
+/** Pull the `error` object out of an envelope or a flat error body. */
+export function extractApiErrorBody(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    if ("object" in body &&
+        body.object === "error" &&
+        "error" in body &&
+        isApiErrorBody(body.error)) {
+        return body.error;
+    }
+    if (isApiErrorBody(body) && typeof body.code === "string") {
+        return body;
+    }
+    return null;
+}
+function extractApiErrorMeta(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    if ("meta" in body) {
+        const meta = body.meta;
+        if (meta && typeof meta === "object") {
+            return meta;
+        }
+    }
+    return null;
+}
+function isApiErrorBody(body) {
+    return typeof body === "object" && body !== null;
+}
+//# sourceMappingURL=errors.js.map