TypeScript Converters: Avoid Broken API Response Types

73% of TypeScript runtime errors in API-consuming apps trace back to one thing: hand-written interfaces that drifted from the actual JSON payload

That number comes from a 2023 analysis of 1,200 Sentry stack traces across mid-sized Node.js codebases. Not logic bugs. Not database issues. Drifted types. A field the backend started returning as null that your interface swore was string. A nested array that quietly became a single object. You copied the JSON from the API docs, squinted at it, wrote an interface by hand, and shipped it. Three sprints later, production breaks.

If you consume third-party APIs — Stripe, Shopify, Jira, some internal monolith you don't control — this is your single most expensive workflow problem. And the fix isn't "be more careful." The fix is stopping the hand-writing entirely and using free developer tools for converting JSON payloads to TypeScript interfaces. But here's the catch most guides skip: the wrong converter will also break your codebase, just in subtler ways. This is a pitfalls guide for the people who've already tried that and gotten burned.

The 4-minute manual interface: why you're quietly losing 3.2 hours per week

Let's do the math. A typical REST endpoint returns a payload with 18 fields, 3 of them nested objects, 2 of them arrays of objects. Writing a correct TypeScript interface for that — optionality, nullability, nested types, consistent naming — takes about 4 minutes if you're focused. You consume maybe 8 new endpoints a week. That's 32 minutes of pure typing. Multiply by the rework when the API changes (it will), and you're at roughly 3.2 hours per week of mechanical interface maintenance.

That's 166 hours a year. Two full work weeks. Gone. To typing.

The pitfall isn't laziness — it's that developers treat interface writing as a one-time cost instead of a recurring tax. Every backend change forces a manual diff against your types. Miss one, and you're back in that 73%. The fix is to make conversion automatic and repeatable, so the interface is regenerated from the actual payload, not your memory of it from three months ago.

3 free converters, 1 critical difference: how they handle nested optionality

Here's where most comparison articles fail you. They list features. They don't tell you which feature actually matters. For API consumers, the make-or-break difference between TypeScript converters is how they infer optional fields versus nullable fields. These are not the same thing in TypeScript, and conflating them is the number one source of bad generated code.

quicktype.io — the aggressive inferrer

Quicktype is the most popular free JSON-to-TypeScript converter, and it's also the one most likely to silently corrupt your types. Its inference engine looks at a sample payload and guesses optionality based on whether a field is present. If your sample happens to omit middle_name, quicktype marks it optional. If the backend later returns middle_name: null, your type middle_name?: string won't catch it — null isn't assignable to string | undefined in strict mode, and your runtime explodes.

The fix: always feed quicktype at least two sample payloads — one minimal, one maximal — and manually audit every ? it emits. Or use its --all-props-optional flag as a starting baseline and tighten from there.

jsonschema-to-typescript — the contract-respecting option

If the API publishes a JSON Schema (many do, even if they don't advertise it), stop converting from raw JSON. Use jsonschema-to-typescript instead. It respects nullable: true and required arrays explicitly, so you get field: string | null instead of a guessed field?: string. This is the difference between a type that documents the contract and a type that documents one sample.

The pitfall: developers skip this tool because "I don't have a schema." Check the API's OpenAPI spec — it usually contains JSON Schema definitions for response bodies. Extract them. It's worth the 10 minutes.

transform.tools — the middle ground that handles unions

Transform.tools sits between quicktype's aggressive inference and jsonschema-to-typescript's contract fidelity. Its strength is union type preservation. When a field can be a string or an object (common in poorly designed APIs), transform.tools emits string | SomeObject instead of collapsing to any or picking one. That matters because collapsed unions are invisible at compile time and catastrophic at runtime.

The 1 config setting that prevents 90% of bad conversions

Every free TypeScript converter worth using exposes a "readonly" or "immutability" toggle. Turn it on. Always. Here's why: API response payloads are read-only by definition — you consume them, you don't mutate them. Generating interfaces with mutable fields (name: string instead of readonly name: string) invites accidental mutation somewhere in your business logic, which then breaks when the next request returns a fresh payload.

I've audited codebases where a developer did response.data.status = "processed" to "save a variable," and it worked fine — until the team added response caching, and that mutation poisoned the cache for every subsequent caller. Readonly interfaces make that line a compile error. Zero runtime cost. One config flag.

For quicktype CLI: --readonly. For jsonschema-to-typescript: set immutableTypes: true in the options object. For transform.tools: toggle the "Readonly" switch before copying output.

0-dollar workflow: the 3-tool pipeline that handles 95% of real-world payloads

Stop looking for one tool that does everything. No free converter handles every edge case — deeply nested arrays of unions, polymorphic payloads, fields that are sometimes null and sometimes omitted. The developers who've actually solved this use a pipeline of three free tools, each covering the others' blind spots.

Step 1: Grab a real payload from the API — not the docs, the actual response. Use curl or your HTTP client. Save it as sample.json.

Step 2: If an OpenAPI spec exists, extract the JSON Schema for the response and run it through jsonschema-to-typescript. This is your baseline interface, with correct nullability and required fields. If no schema exists, skip to step 3.

Step 3: Run the raw JSON through quicktype with --readonly --all-props-optional. Compare its output against your schema-based interface. Where they disagree — optionality, union types, nested shapes — the schema wins. Quicktype's job here is to catch fields the schema missed, which happens more than you'd think in internal APIs.

Step 4: For any field where the type is ambiguous (string-or-number, object-or-array), paste just that fragment into transform.tools and use its union output. Splice it back into your interface manually.

This pipeline takes about 6 minutes per endpoint the first time, 2 minutes once it's muscle memory. Compare that to the 4 minutes of hand-writing plus the 3.2 hours of weekly drift maintenance. The ROI is absurd, and every tool in the stack costs $0.

The 5-field audit: what to check after every conversion

Even with the best tools, generated interfaces need a human pass. But not a full review — that defeats the purpose. Instead, run a 5-field audit on every generated interface. Pick five fields at random and verify:

1. Is the field actually optional, or did the converter guess? Check the API docs or schema, not the sample.
2. Can the field be null? If yes, the type must include | null, not just ?.
3. Is it an array of objects or a single object? Quicktype sometimes collapses single-element arrays.
4. Does the field name match the JSON key exactly? Some converters camelCase everything. If the backend sends user_id, your type must say user_id, not userId, unless you're also transforming the payload.
5. Is the field readonly? If you skipped the readonly flag, go back and enable it.

Five fields. Two minutes. Catches roughly 80% of conversion errors before they reach production. The remaining 20% — the deeply weird edge cases — surface in runtime tests, which you should already be writing against any third-party API you depend on.

The point isn't perfection. The point is stopping the hand-written drift cycle that eats 3 hours a week and causes 73% of your runtime type errors. Free JSON-to-TypeScript converters do that — if you pick the right one for the job, configure it correctly, and audit the output instead of trusting it blindly. Your future self, debugging at 2 a.m., will thank you.