Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

19.2 KB
Raw Blame
import { dayjs } from 'lib/dayjs'
import { humanFriendlyDuration } from 'lib/utils/durations'

/** A 403 with DRF's `permission_denied` code — the user lacks access to the resource itself. */
export function isAccessDeniedError(error: { status?: number; code?: string | null }): boolean {
    return error.status === 403 && error.code === 'permission_denied'
}

/** DRF code for `PostHogFeatureFlagPermission` (posthog/permissions.py). Keep in sync with the backend. */
export const FEATURE_FLAG_REQUIRED_ERROR_CODE = 'feature_flag_required'

/**
 * A 403 from a feature flag gate rather than from access control: the flag behind the product
 * is not on for this user yet. Early access enrollment reaches the server as an ingested person
 * property, so this is also what the seconds right after enabling a feature preview look like,
 * while the browser already evaluates the flag as on.
 */
export function isFeatureFlagGatedError(error: unknown): boolean {
    const failure = error as { status?: number; code?: string | null } | null
    return failure?.status === 403 && failure?.code === FEATURE_FLAG_REQUIRED_ERROR_CODE
}

/** DRF code for `ClickHouseQueryMemoryLimitExceeded` (posthog/exceptions.py). Keep in sync with the backend. */
export const CLICKHOUSE_MEMORY_LIMIT_ERROR_CODE = 'clickhouse_memory_limit_exceeded'

export const TABLE_ACCESS_DENIED_ERROR_CODE = 'table_access_denied'

/**
 * A 409 from the approvals gate: the change was policy-gated and a change request was created,
 * or one is already pending. Approval 409 bodies always carry `change_request_id`
 * (see products/approvals/backend/decorators.py).
 */
export function isApprovalRequiredError(error: { status?: number; data?: any } | null | undefined): boolean {
    return error?.status === 409 && Boolean(error?.data?.change_request_id)
}

/** The flag API refuses an edit that lowers exposure when the request asks for a reason and sends none. */
export function isRollbackReasonRequiredError(
    error: { status?: number; code?: string | null } | null | undefined
): boolean {
    return error?.status === 409 && error?.code === 'rollback_reason_required'
}

/** Potentially transient failures; a gateway error does not prove that the backend did no work. */
const TRANSIENT_GATEWAY_STATUSES: ReadonlySet<number> = new Set([502, 503, 504])

function isTransientGatewayStatus(status: number | undefined): boolean {
    return status !== undefined && TRANSIENT_GATEWAY_STATUSES.has(status)
}

/**
 * A transient gateway failure (502/503/504) rather than anything the caller did wrong. These
 * often arrive with an empty body (so `detail` is null) and usually succeed on retry, so a
 * listener that has already shown a toast should stop here instead of rethrowing into
 * unhandled-rejection tracking. A plain 500 is excluded on purpose: it signals an application
 * bug, so it should keep surfacing its `detail` and reach error tracking.
 */
export function isTransientServerError(error: unknown): boolean {
    return error instanceof ApiError && isTransientGatewayStatus(error.status)
}

/**
 * A route the backend does not serve: the path is unknown (404), or it is known but does not accept
 * the method (405). Both are what a deploy in progress looks like from the browser, since the
 * frontend bundle can reach a backend that does not have the endpoint yet. A new `detail=False`
 * DRF action reads as 405 rather than 404, because the router still matches the detail route and
 * only then refuses the method.
 *
 * This is deliberately not part of `shouldReportApiFailure`: a 404 on a resource the app expects to
 * exist is a real defect, so only a caller that already degrades to a partial view should excuse
 * one. Use it there, next to the code that renders the degraded state.
 */
export function isUnavailableEndpointError(error: unknown): boolean {
    if (error === null || typeof error !== 'object') {
        return false
    }
    const status = (error as { status?: number }).status
    return status === 404 || status === 405
}

/**
 * The DRF `detail` values `posthog/api/routing.py` raises when a URL's scope no longer resolves.
 * This is user-facing copy that the backend plans to rename (`Project` to `Environment`), so the
 * match is fragile: keep this set in sync with those raise sites, which point back here.
 */
const SCOPE_NOT_FOUND_DETAILS: ReadonlySet<string> = new Set(['Project not found.', 'Organization not found.'])

/**
 * A 404 raised because the project or organization in the URL no longer resolves - it was deleted,
 * or the user lost access to it. Every endpoint under that scope answers the same way, so the
 * failure describes the URL the user sits on rather than the request that hit it, and repeating
 * that request cannot make it succeed.
 *
 * Narrower than `isUnavailableEndpointError` on purpose, and unlike that one it is safe to excuse
 * globally: a dead scope is read off the `detail`, so a 404 from a resource the app expects to
 * exist still reports.
 */
export function isScopeNotFoundError(error: unknown): boolean {
    const failure = error as { status?: unknown; detail?: unknown; data?: { detail?: unknown } } | null
    if (failure?.status !== 404) {
        return false
    }
    return isScopeNotFoundMessage(failure.detail ?? failure.data?.detail)
}

/**
 * Whether a message is the `detail` of a dead scope. An `ApiError` takes its message from that
 * `detail`, and the automatic unhandled-rejection capture keeps the message but not the status, so
 * `before_send` can only match on this.
 */
export function isScopeNotFoundMessage(message: unknown): boolean {
    return typeof message === 'string' && SCOPE_NOT_FOUND_DETAILS.has(message)
}

/** DRF `detail` of the project membership 403s in posthog/permissions.py. Keep in sync with the backend. */
export const PROJECT_ACCESS_DENIED_DETAIL = "You don't have access to the project."

/** DRF code of a security access rule refusal (products/security). Keep in sync with the backend. */
export const ACCESS_BLOCKED_ERROR_CODE = 'access_blocked'

/** The 403 gates `apiStatusLogic` recovers from, keyed by the DRF `code` the backend sends. */
const HANDLED_AUTH_GATE_CODES: ReadonlySet<string> = new Set([
    'two_factor_setup_required',
    'two_factor_verification_required',
    'sensitive_action_required_reauth',
])

/**
 * How each browser engine words a `fetch` that never reached the server. Chromium says "Failed to
 * fetch", WebKit "Load failed", and Gecko "NetworkError when attempting to fetch resource.".
 */
export const BROWSER_FETCH_FAILURE_MESSAGES: readonly string[] = [
    'Failed to fetch',
    'Load failed',
    'NetworkError when attempting to fetch resource',
]

/**
 * A module the browser could not load, which is a defect of ours rather than connectivity: a chunk
 * an open tab still asks for went missing in a deploy. Chromium and Gecko word this by extending
 * one of the messages above, so a module failure has to be recognized before a connectivity one.
 *
 * `isChunkLoadError` answers a wider question, whether to retry the import or offer a reload, and
 * so it also treats a bare "Load failed" as a stale chunk. That guess is wrong for this decision,
 * because it would keep reporting every WebKit connectivity failure.
 */
const MODULE_LOAD_FAILURE_MESSAGES: readonly string[] = [
    'dynamically imported module',
    'Importing a module script failed',
]

/**
 * A `fetch` the browser refused to complete, recognized by the message the engine produced. The
 * request never reached the server, so there is no status to react to and no code path of ours to
 * fix: the cause is an ad blocker, tracking protection, DNS, a captive portal, or a connection that
 * dropped mid-request.
 *
 * The match is on the message and not on the `TypeError` class on purpose. Application bugs raise
 * status-less `TypeError`s too, such as "x is not a function", and dropping those would hide real
 * crashes.
 */
export function isBrowserNetworkFailure(error: unknown): boolean {
    if (error === null || typeof error !== 'object') {
        return false
    }
    const message = (error as { message?: unknown }).message
    if (typeof message !== 'string') {
        return false
    }
    if (MODULE_LOAD_FAILURE_MESSAGES.some((known) => message.includes(known))) {
        return false
    }
    return BROWSER_FETCH_FAILURE_MESSAGES.some((known) => message.includes(known))
}

/**
 * Whether a failed request is worth filing as an error tracking issue. A response the app asked
 * for and recovers from itself is not a defect, and reporting it buries the ones that are: every
 * `ApiError` is built in this file, so they all share one stack, and grouping ignores the message
 * once that stack resolves, which lands a handled 401 in the same issue as a genuine crash.
 *
 * Left unreported, because something else already resolves them for the user:
 * - 401 — an authentication state rather than a crash. `apiStatusLogic` re-checks the session and
 *   logs the user out, best-effort: it bails while impersonating (where `ImpersonationNotice`
 *   offers re-impersonation instead), before the user has loaded, and within 10s of its last check.
 * - 403 `permission_denied` — the sceneLogic gates render the AccessDenied scene.
 * - 403 auth gates — `apiStatusLogic` opens 2FA setup, re-verification, or a re-auth prompt.
 * - 409 carrying a `change_request_id` — the approvals UI shows the change request it created.
 * - 409 carrying a `current_version` — an optimistic-concurrency conflict (experiments). The
 *   editing surface toasts, reloads the fresh state, and keeps the user's unsaved edits.
 * - 404 `Project not found.` / `Organization not found.` — the scope in the URL is gone, so every
 *   request under it fails the same way. The scene routing takes the user off that URL, and until
 *   it does, a poll on the dead scope would otherwise file one exception per tick.
 * - 502/503/504 are gateway or upstream failures. The backend may already have started the request.
 *
 * Left unreported for a second reason, that there is nothing to fix:
 * - a `fetch` the browser never completed. No request reached us, so no code of ours failed, and
 *   the user is told by whatever the caller renders for an empty result. Reporting these is what
 *   floods the project: grouping is stack-based, so every loader that meets the same connectivity
 *   blip opens an issue of its own, and one bad minute on a user's network manufactures dozens.
 * - a 2xx response whose body stream failed mid-read. The server already answered successfully, so
 *   the truncation happened on the wire, not in application code. These group the same stack-based
 *   way, so one flaky connection opens an issue per endpoint it touched. `api.ts` captures each one
 *   as a `client_request_failure` with `failure_reason: 'response_body_read'`, so a persistent
 *   truncation regression is still visible in aggregate without an issue per endpoint.
 *
 * Each of these still toasts wherever it did before, and `client_request_failure` still records
 * every non-OK response with its status and pathname, so failure rates stay queryable even where
 * no recovery runs. That event is also the better record, since an exception raised here cannot say
 * which endpoint failed: every `ApiError` shares this file's stack.
 *
 * A plain 500 stays reportable on purpose, being a genuine backend exception. So does a status-less
 * failure that is not a recognized connectivity failure, such as a thrown string, a bare `Error`,
 * or an application `TypeError`, because there is no response to excuse it. A failed module import
 * keeps reporting too, since a stale chunk after a deploy is a defect we can fix.
 */
export function shouldReportApiFailure(error: unknown): boolean {
    if (isBrowserNetworkFailure(error)) {
        return false
    }
    if (error instanceof ResponseBodyReadError) {
        return false
    }
    if (error === null || typeof error !== 'object') {
        return true
    }
    const failure = error as { status?: number; code?: string | null; data?: any }
    const status = typeof failure.status === 'number' ? failure.status : undefined
    if (status === undefined) {
        return true
    }
    if (status === 401 || isTransientGatewayStatus(status)) {
        return false
    }
    if (isScopeNotFoundError(failure)) {
        return false
    }
    if (isAccessDeniedError(failure)) {
        return false
    }
    if (status === 403 && failure.code != null && HANDLED_AUTH_GATE_CODES.has(failure.code)) {
        return false
    }
    if (status === 409 && failure.data?.current_version !== undefined) {
        return false
    }
    if (isRollbackReasonRequiredError(failure)) {
        return false
    }
    return !isApprovalRequiredError(failure)
}

/**
 * The readable message a failure carries, whether it arrived as a parsed error response body or as
 * a value something in the request path threw. Returns undefined when nothing readable is there, so
 * the caller falls back to its own wording instead of printing `[object Object]`.
 */
export function readableErrorMessage(error: unknown): string | undefined {
    if (typeof error === 'string') {
        return error || undefined
    }
    if (error === null || typeof error !== 'object') {
        return undefined
    }
    const failure = error as Record<string, unknown>
    return [failure.error, failure.detail, failure.message].find(
        (value): value is string => typeof value === 'string' && value.length > 0
    )
}

export class ApiError extends Error {
    /** Numeric capacity hints can be used for automatic retries without relying on server or device clocks. */
    readonly retryAfterSeconds: number | null
    /** An absolute deadline keeps rerenders and remounts from restarting a capacity cooldown. */
    readonly retryAfterTimestamp: number | null
    /** Django REST Framework `detail` - used in downstream error handling. */
    detail: string | null
    /** Django REST Framework `code` - used in downstream error handling. */
    code: string | null
    /** Django REST Framework `statusText` - used in downstream error handling. */
    statusText: string | null
    /** Django REST Framework `attr` - used in downstream error handling. */
    attr: string | null

    /** Link to external resources, e.g. stripe invoices */
    link: string | null

    constructor(
        message?: string,
        public status?: number,
        public headers?: Headers,
        public data?: any
    ) {
        message = message || `API request failed with status: ${status ?? 'unknown'}`
        super(message)
        this.statusText = data?.statusText || null
        this.detail = data?.detail || null
        this.code = data?.code || null
        this.link = data?.link || null
        this.attr = data?.attr || null
        const retryAfter = status === 503 ? headers?.get('Retry-After') : null
        const seconds = retryAfter && /^\d+$/.test(retryAfter) ? Number(retryAfter) : NaN
        this.retryAfterSeconds = Number.isSafeInteger(seconds) ? seconds : null
        const retryAfterTimestamp = this.retryAfterSeconds !== null ? Date.now() + this.retryAfterSeconds * 1000 : NaN
        this.retryAfterTimestamp = Number.isSafeInteger(retryAfterTimestamp) ? retryAfterTimestamp : null
    }

    static async fromResponse(response: Response, fallbackMessage?: string): Promise<ApiError> {
        let data: unknown = null

        try {
            data = await response.json()
        } catch (error) {
            if ((error as { name?: string } | null)?.name === 'AbortError') {
                throw error
            }
        }

        const errorData = data && typeof data === 'object' ? data : null

        return new ApiError(readableErrorMessage(errorData) || fallbackMessage, response.status, response.headers, data)
    }

    /**
     * For when the API returned a 429 (Too Many Requests) error:
     * If the `Retry-After` header is present, return a human-friendly duration, e.g. "in 4 hours", otherwise just "later".
     * Return null for other status codes.
     */
    get formattedRetryAfter(): string | null {
        if (this.status !== 429) {
            return null
        }
        if (this.headers?.has('Retry-After')) {
            const retryAfter = this.headers.get('Retry-After') as string
            let secondsLeft = Number(retryAfter) // Let's assume we're dealing with an integer by default
            if (isNaN(secondsLeft)) {
                // Nope, here we're dealing with date in this format: Wed, 21 Oct 2015 07:28:00 GMT
                secondsLeft = dayjs(retryAfter).diff(dayjs(), 'seconds')
            }
            return `in ${humanFriendlyDuration(secondsLeft, { maxUnits: 2 })}`
        }
        return 'later'
    }
}

/**
 * Why a request never reached the server. `offline` and `navigating` describe the state of the
 * client rather than a fault in the request path, so they are dropped before they reach error
 * tracking (see `dropUnactionableNetworkExceptions`). `network` is the residue that is worth
 * looking at: an ad blocker, a misconfigured reverse proxy, DNS, a CDN, or our own edge.
 */
export type NetworkFailureReason = 'offline' | 'navigating' | 'network'

/**
 * One fixed message per reason. Two constraints meet here. The browser's own wording varies by
 * engine ("Failed to fetch", "Load failed", "NetworkError when attempting to fetch resource."),
 * and the automatic unhandled-rejection capture carries no custom properties, so the message is
 * the only place the reason can travel to `before_send` and to error tracking grouping rules.
 */
export const NETWORK_ERROR_MESSAGES = {
    offline: 'Network request failed: device is offline',
    navigating: 'Network request failed: page was closing',
    network: 'Network request failed',
} as const satisfies Record<NetworkFailureReason, string>

/** The reasons that are never a defect, so filing them as error tracking issues only adds noise. */
export const UNACTIONABLE_NETWORK_ERROR_MESSAGES: ReadonlySet<string> = new Set([
    NETWORK_ERROR_MESSAGES.offline,
    NETWORK_ERROR_MESSAGES.navigating,
])

/**
 * A request the browser never completed, so there is no HTTP status to react to. `status` is left
 * undefined on purpose: recovery paths across the app read `status === undefined` as "transient,
 * may be retried" (for example `inviteSignupLogic` and `sourcesDataLogic`), and a placeholder like
 * 0 would make them treat a connectivity blip as a client error.
 */
export class NetworkError extends ApiError {
    constructor(
        public reason: NetworkFailureReason,
        cause?: unknown
    ) {
        super(NETWORK_ERROR_MESSAGES[reason])
        // Sets the `type` posthog-js reports in `$exception_list`, which is what
        // `dropUnactionableNetworkExceptions` and error tracking grouping rules match on.
        this.name = 'NetworkError'
        this.cause = cause
    }
}

/**
 * A 2xx response whose body stream failed part way through, after the server had already answered
 * successfully: a dropped connection or a proxy hiccup truncating a chunked response, not an
 * application defect. It extends `ApiError` so that every existing catch path degrades as before.
 */
export class ResponseBodyReadError extends ApiError {
    constructor(message: string) {
        super(message)
        // Sets the `type` posthog-js reports in `$exception_list`, which error tracking grouping
        // rules match on.
        this.name = 'ResponseBodyReadError'
    }
}