Meta tags:
description=How to catch and handle Headroom errors in Python and TypeScript. Error hierarchy, proxy error mapping, and safety guarantees.;

Headings (most frequently used words):

error, handling, hierarchy, catching, errors, types, in, detail, proxy, mapping, details, safety, guarantee, best, practices, configurationerror, providererror, storageerror, compressionerror, headroomconnectionerror, typescript, on, this, page,

Text of the page (most frequently used words):
error (31), headroom (23), #compression (18), proxy (15), configurationerror (14), the (13), #details (12), print (11), headroomerror (11), typescript (10), storageerror (10), import (9), model (9), provider (9), from (9), headroomconnectionerror (8), providererror (8), and (8), when (8), client (8), errors (7), except (7), try (7), 4xx (7), 5xx (7), configuration (6), messages (6), headroomcompresserror (6), raised (6), metrics (6), failed (6), failures (6), safety (5), issues (5), invalid (5), with (5), catch (5), storage (5), content (5), python (5), headroomautherror (5), sdk (5), console (5), instanceof (5), compress (5), mapping (4), compressionerror (4), this (4), for (4), not (4), logging (4), exception (4), response (4), passes (4), through (4), unchanged (4), field (4), type (4), headroomclient (4), mapproxyerror (4), validationerror (4), class (4), message (4), handling (4), guarantee (3), hierarchy (3), token (3), warning (3), core (3), exceptions (3), gpt (3), chat (3), completions (3), create (3), fails (3), original (3), which (3), config (3), statuscode (3), context (3), configuration_error (3), cannot (3), without (3), unknown (3), api (3), else (3), cache (3), best (2), practices (2), types (2), detail (2), catching (2), startup (2), savings (2), installation (2), troubleshooting (2), limitations (2), json (2), level (2), affect (2), functionality (2), specific (2), malformed (2), will (2), raise (2), your (2), llm (2), calls (2), never (2), fail (2), was (2), include (2), returns (2), mode (2), const (2), transformerror (2), tokenizationerror (2), 401 (2), await (2), rare (2), continue (2), historical (2), database (2), operations (2), get (2), counting (2), failure (2), openai (2), issue (2), reach (2), validation (2), base (2), how (2), architecture (2), reference (2), server (2), memory (2), reversible (2), page, solutions, common, including, connection, high, latency, problems, helps, does, what, watch, out, honest, documentation, constraints, gates, transforms, smart_crusher, skipping, basicconfig, see, skipped, enable, early, validate_setup, validate, let, pass, rather, than, broad, avoid, hiding, real, bugs, tool, role, due, original_error, underlying, requested, involved, caused, might, __name__, also, has, errortype, record, string, any, undefined, all, dict, object, additional, instance, 400, function, handles, other, transform_error, validation_error, tokenization_error, storage_error, provider_error, http, status, automatically, maps, responses, correct, running, start, connect, practice, are, caught, internally, only, strict, get_metrics, application, can, xyz, invalid_mode, default_mode, openaiprovider, original_client, its, thrown, continues, work, just, persistence, auth, result, setup, etc, transform, execution, cacheerror, provides, explicit, debugging, break, open, copy, markdown, handle, guarantees, help, benchmarks, simulation, monitoring, observability, mcp, tools, litellm, strands, agno, langchain, anthropic, vercel, integrations, learning, sharedcontext, persistent, management, optimization, ccr, text, log, image, code, smartcrusher, works, community, quickstart, introduction, getting, started, search,

Text of the page (random words):
error handling headroom headroom headroom search k getting started introduction quickstart installation community savings compression how compression works smartcrusher code compression image compression text log compression reversible compression reversible compression ccr cache context cache optimization context management memory persistent memory sharedcontext failure learning proxy server proxy server integrations vercel ai sdk openai sdk anthropic sdk langchain agno strands litellm mcp tools configuration configuration observability metrics monitoring simulation api reference api reference architecture architecture benchmarks limitations help error handling troubleshooting error handling error handling how to catch and handle headroom errors in python and typescript error hierarchy proxy error mapping and safety guarantees copy markdown open headroom provides explicit exceptions for debugging with a core safety guarantee compression failures never break your llm calls if compression fails the original content passes through unchanged error hierarchy typescript python headroomerror base class headroomconnectionerror cannot reach proxy headroomautherror 401 from proxy headroomcompresserror compression failed with statuscode configurationerror invalid configuration providererror provider issues storageerror storage failures tokenizationerror token counting failed cacheerror cache operations failed validationerror validation failures transformerror transform execution failed import headroomerror headroomconnectionerror headroomautherror headroomcompresserror configurationerror providererror mapproxyerror from headroom ai headroomerror base class configurationerror invalid configuration providererror provider issues unknown model etc storageerror database storage failures compressionerror compression failures rare validationerror setup validation failures from headroom import headroomerror configurationerror providererror storageerror compressionerror validationerror catching errors typescript python import compress headroomconnectionerror headroomautherror headroomcompresserror headroomerror from headroom ai try const result await compress messages model gpt 4o catch e if e instanceof headroomconnectionerror console error cannot reach proxy e message else if e instanceof headroomautherror console error auth failed e message else if e instanceof headroomcompresserror console error compress failed e statuscode e message else if e instanceof headroomerror console error headroom error e message e details from headroom import headroomclient headroomerror configurationerror storageerror try client headroomclient response client chat completions create except configurationerror as e print f config issue e print f details e details except storageerror as e print f storage issue e headroom continues to work just without metrics persistence except headroomerror as e print f headroom error e error types in detail configurationerror raised when configuration is invalid typescript python import configurationerror from headroom ai configurationerror is thrown when the proxy returns a configuration_error type in its error response try client headroomclient original_client openai provider openaiprovider default_mode invalid_mode will raise configurationerror except configurationerror as e print f config error e print f field e details get field providererror raised for provider specific issues unknown model api error token counting failure try response client chat completions create model unknown model xyz messages except providererror as e print f provider error e print f provider e details get provider storageerror raised when database operations fail storage errors do not affect core functionality the application can continue without historical metrics try metrics client get_metrics except storageerror as e metrics continue without historical metrics compressionerror raised when compression fails rare in practice compression errors are caught internally and the original content passes through unchanged this exception is only raised in strict mode headroomconnectionerror typescript raised when the typescript sdk cannot connect to the headroom proxy import compress headroomconnectionerror from headroom ai try await compress messages model gpt 4o catch e if e instanceof headroomconnectionerror console error is the proxy running start with headroom proxy proxy error mapping the typescript sdk automatically maps proxy error responses to the correct error class http status proxy error type typescript class 401 headroomautherror 4xx 5xx configuration_error configurationerror 4xx 5xx provider_error providererror 4xx 5xx storage_error storageerror 4xx 5xx tokenization_error tokenizationerror 4xx 5xx validation_error validationerror 4xx 5xx transform_error transformerror 4xx 5xx other headroomcompresserror the mapproxyerror function handles this mapping import mapproxyerror from headroom ai const error mapproxyerror 400 configuration_error invalid mode returns a configurationerror instance error details all headroom exceptions include a details dict object with additional context typescript python import headroomerror from headroom ai headroomerror details is record string any undefined headroomcompresserror also has statuscode and errortype try client headroomclient except headroomerror as e print f error e print f type type e __name__ print f details e details details might include field which config field caused the error provider which provider was involved model which model was requested original_error underlying exception safety guarantee if compression fails the original content passes through unchanged your llm calls never fail due to headroom messages role tool content malformed json this will not raise an exception the malformed content passes through unchanged response client chat completions create model gpt 4o messages messages best practices catch specific exceptions rather than broad exception to avoid hiding real bugs let storageerror pass storage errors do not affect core compression functionality validate on startup with client validate_setup to catch configuration issues early enable logging at warning level to see when compression is skipped import logging logging basicconfig level logging warning warning headroom transforms smart_crusher skipping compression invalid json limitations when headroom helps when it does not and what to watch out for honest documentation of compression constraints and safety gates troubleshooting solutions for common headroom issues including proxy startup connection errors no token savings high latency and installation problems on this page error hierarchy catching errors error types in detail configurationerror providererror storageerror compressionerror headroomconnectionerror typescript proxy error mapping error details safety guarantee best practices