2026-04-09 | 🎯 Typed Errors for the Gemini Module 🛡️
🧭 Context
🏗️ This post continues the Haskell architecture improvement journey, picking up right where the AppContext Record phase left off.
🔍 The Gemini AI module previously used raw Text strings inside Either values to communicate errors, meaning every caller had to do fragile string pattern matching to distinguish rate limits from parse failures from HTTP errors.
🎪 One particularly gnarly example lived in the InternalLinking module, where two functions called isRateLimitErr and isDailyQuotaErr searched error text for substrings like “429”, “RESOURCE_EXHAUSTED”, and “quota” to decide whether to retry or give up.
🛠️ What Changed
🏷️ We introduced a domain-specific Error algebraic data type directly within the Gemini module, following the library-developer module design principle where each module owns its own types.
🔌 Critically, we grounded our error detection in the official Gemini API documentation at ai.google.dev/gemini-api/docs/troubleshooting. The API returns structured error JSON with a machine-readable “status” field, so we parse that field into a proper ApiStatus ADT with constructors for every documented status: ResourceExhausted, InvalidArgument, PermissionDenied, NotFound, InternalError, Unavailable, DeadlineExceeded, Unauthenticated, FailedPrecondition, and UnknownStatus for forward compatibility.
🏷️ The Error type has four constructors. JsonParseError means the response body was not valid JSON. ExtractionError carries a detail string explaining which field was missing from the response structure, such as “no candidates in response” or “no text in part”. HttpError carries the HTTP status code, the parsed ApiStatus, and the human-readable message from the API. AllModelsFailed wraps the last model tried (as a typed Model value, not a raw string) and the inner error from that final attempt, forming a recursive structure.
🚫 Notably, we removed the NoModelsProvided constructor entirely. Instead of accepting a list of models that could be empty and handling it as a runtime error, the function signature now uses NonEmpty from Haskell’s standard library. This dissolves the impossible state at the type level, following the principle that invalid inputs should be unrepresentable rather than handled by runtime error constructors.
🏷️ Model ADT
🔢 Gemini model names were previously raw Text strings scattered across modules. But the set of models our system uses is known and fixed at compile time, making it a classic closed set. Following the AGENTS.md principle that closed sets deserve ADTs, we introduced a Model sum type with seven constructors: Gemma3, Gemini31FlashLite, Gemini3Flash, Gemini25Flash, Gemini25FlashLite, Gemini20Flash, and Gemini31FlashImage. A Custom constructor with a Text payload preserves the ability to override models via environment variables.
🔄 Round-trip functions modelToText and modelFromText convert between the ADT and the raw API strings. The fromText function recognizes all seven known model strings and falls back to Custom for anything else. A knownModels list exports all known constructors for exhaustive property testing.
🧱 The migration touched twelve source and test files. AllModelsFailed in the Error ADT now carries Model instead of Text. BlogImage’s geminiModelFallback function was rewritten from string prefix matching to clean constructor pattern matching. All env-var overrides parse into Model at the boundary using modelFromText, so the rest of the system never handles raw model strings. Feature modules like AiFiction and ReflectionTitle now import the Gemini.Model type for their config records, making the implicit coupling explicit through the type system.
🚫 NonEmpty Model Chains
📋 Every function that needs at least one model now uses NonEmpty Model instead of a plain list. This includes generateContentWithFallback, callGeminiForGenerator, and the config records in FictionConfig, ReflectionTitleConfig, and BlogSeriesRunConfig. The change dissolved three separate runtime error calls that previously guarded against empty lists, including “Blog series model chain is empty” and “No models provided for Gemini generation”. These states are now unrepresentable.
🧩 Haskell’s standard Data.List.NonEmpty provides the NonEmpty type along with the colon-pipe constructor for pattern matching. The head element is always guaranteed to exist, so generateContentWithFallback destructures the NonEmpty into a primary model and a possibly-empty fallback list in one pattern. No case-match-on-empty, no runtime error, no impossible state.
🔄 Environment variable overrides that prepend a parsed model to the chain now construct NonEmpty values directly using the colon-pipe constructor. Since we always know we have at least one model after prepending, the type checker confirms the guarantee without needing a runtime check.
🔍 Rate limit detection is now based on constructor matching rather than string inspection. The isRateLimitError predicate simply matches HttpError with ResourceExhausted status, which is the official API status code for rate limiting. No more searching the body for “RESOURCE_EXHAUSTED” or “quota” as substrings. The isQuotaExhaustedError predicate refines further by checking whether the message mentions “daily” or “per day”, since both per-minute rate limits and daily quota exhaustion return ResourceExhausted.
📝 Callers use the derived Show instance for display. There is no custom renderError function that would tempt callers to unwrap structured errors back into opaque text. Show preserves the full structure, including the ApiStatus constructor name, so log messages remain informative.
📊 Migration Impact
🗂️ Four caller modules were updated. RunScheduled uses show when converting errors to exception messages. BlogImage pattern-matches the result at the boundary. SocialPosting wraps show in its “Tags generation failed” and “Question generation failed” messages. InternalLinking saw the biggest improvement, replacing its local isRateLimitErr and isDailyQuotaErr text-matching functions with calls to the typed Gemini.isRateLimitError and Gemini.isQuotaExhaustedError predicates.
🧹 The dead isRateLimitErr and isDailyQuotaErr functions were removed from InternalLinking, along with the renderError function from Gemini, following the no dead code policy.
🔀 The generateContentWithFallback signature changed from taking a plain list to taking a NonEmpty Model. All call sites were updated to construct NonEmpty values directly using the colon-pipe constructor.
🧪 Testing
✅ Over sixty new tests cover every aspect of the error system. The ApiStatus tests verify round-trip parsing for all nine documented status values and the UnknownStatus fallback.
🔬 The rate limit and quota exhausted predicates are tested exclusively through ApiStatus constructor matching. ParseResponseText and extractText tests exercise every failure path through the JSON extraction logic. ParseErrorBody tests verify parsing of structured Gemini error JSON, including fallback behavior for non-JSON responses and missing fields.
📈 Property-based tests verify that show always produces non-empty output for any generated error, that HttpError with ResourceExhausted is always classified as a rate limit, that all nine known ApiStatus values round-trip correctly through parseApiStatus, and that all seven known Model values round-trip through modelToText and modelFromText.
🏁 The test suite grew from 942 to 1021 tests, all passing with zero warnings under the strict -Werror flag.
🔮 What Comes Next
🗺️ The architecture roadmap continues with explicit error types for the platform modules (Twitter, Bluesky, Mastodon), replacing silent empty-string returns with Maybe or Either, and eliminating error function calls in non-startup code paths.
💡 Lessons Learned
🔬 Ground detection in official docs: match error conditions on machine-readable fields from the API, not on ad-hoc string patterns in the body.
🧩 Dissolve impossible states at the type level: instead of adding an error constructor for “no models provided,” use NonEmpty from Haskell’s standard library to encode the at-least-one guarantee statically. This eliminated three separate runtime error calls in our codebase.
🚫 Do not unwrap typed errors back to Text: the Show instance preserves full structure, and a custom renderError encourages callers to discard type information.
🔌 Parse external APIs at the boundary: when the API returns structured error JSON, parse it immediately into a typed ADT so downstream code never sees raw response bodies.
🔢 Closed sets deserve ADTs: when a value comes from a known fixed set, even one that evolves over time like model names, represent it as a sum type with a Custom escape hatch. This eliminates typos, enables constructor pattern matching for fallback logic, and provides round-trip guarantees via property tests. The env-var override boundary is where raw text enters; everything beyond that point uses the typed value.
📛 No abbreviations in field names or variable bindings: use responseText and responseModel instead of grText and grModel, and response instead of resp. Names should be self-documenting without relying on positional context.
📚 Book Recommendations
📖 Similar
- Domain Modeling Made Functional by Scott Wlaschin is relevant because it demonstrates how algebraic data types and domain-specific error types prevent entire categories of bugs, which is exactly the approach this change takes.
- Haskell in Depth by Vitaly Bragilevsky is relevant because it covers advanced Haskell patterns including proper error handling strategies with Either and custom error types.
↔️ Contrasting
- Release It! by Michael T. Nygard offers a contrasting perspective focused on runtime resilience patterns like circuit breakers and bulkheads rather than compile-time type safety for error handling.
🔗 Related
- Algebra-Driven Design by Sandy Maguire explores how algebraic thinking shapes software design, directly relating to the algebraic data type approach used for the Gemini Error type.
- Software Design for Flexibility by Chris Hanson and Gerald Jay Sussman examines how to build systems that gracefully handle change and extension, connecting to the library-developer module design principle followed here.