---
name: remote-api-footguns
description: "Remote API traps in Kotlin Multiplatform: Ktor clients, defensive parsing, Resource envelopes, OK responses that dropped your data, auth callbacks, retry backoff, downloads, websockets, clock sync. Use when calls succeed but data never lands."
---

# Remote API footguns

17 traps mined from a production Kotlin and Compose Multiplatform app, one short file each
under `references/`. Every file gives the working pattern, the **Traps** (the specific ways it
fails in practice, and why), and a **Verifying it** section with commands to run against the
user's own tree.

**How to use this index.** Match the code about to be written, or the symptom being chased,
against the entries below: each names its topic and the symptom that should send you to it. Read
every file that plausibly applies with the Read tool before proposing code or a fix; each is under
150 lines. Where a Verifying command names the source project's paths, substitute the equivalent
paths in the user's tree.

**Cross-references.** A backticked trap name inside a file that is not listed here lives in a
sibling area skill: glob `../*/references/<name>.md` to open it.

## Clients, parsing and response handling

- [`ktor-kmp-client-architecture`](references/ktor-kmp-client-architecture.md) — A multiplatform HTTP stack where one expect/actual hands back the engine and each integration builds its own client from it — an instrumented client for API calls next to a deliberately bare one for bulk downloads, content negotiation registered per format, and a settings change that rebuilds the client rather than mutating it. Use when standing up networking in a Kotlin Multiplatform module, when a proxy setting appears to be ignored by some requests but not others, or when downloading a large file crawls and floods the log.
- [`curl-logger-ktor-plugin`](references/curl-logger-ktor-plugin.md) — A client plugin that logs every outgoing request as one paste-ready curl command — POSIX single-quoting so a body full of quotes, dollars or newlines survives the shell, the whole command in a single log call, a redaction list, and a body read that does not consume a one-shot channel. Use when you want to replay a failing request outside the app, when a logged command will not run when pasted, or when reproducing a bug means rebuilding a request by hand from a log.
- [`parallel-chunked-download`](references/parallel-chunked-download.md) — Splitting one file into N byte-range requests issued in parallel over a bare HTTP client, each chunk to its own temp file, merged in order, with progress reported through a channel-backed flow — plus when ranges are actually safe, how big a chunk should be, and why a failure retries one chunk rather than the file. Use when a large download is slower than the link allows, when a download restarts from zero after a hiccup, or when a progress bar sticks just short of full.
- [`structural-defensive-parsing`](references/structural-defensive-parsing.md) — Reading a response whose shape drifts — classify each field by the marker the payload itself declares rather than by its position, treat a filtering map as data loss and count what it drops, refuse to substitute a placeholder for a failed parse, and parse composite strings from their stable end. Use when a parser works in one locale and not another, when a list arrives shorter than the source shows, or when a made-up value turns up somewhere it was never entered.
- [`response-to-domain-flow`](references/response-to-domain-flow.md) — The five stages a remote response passes through — transport model in a per-integration service module, a pure parser layer, a domain model, a result envelope, then collection — with the rule that each integration is its own module so one source's breakage cannot spread, and the placement rules that keep transport types out of screens. Use when adding a second remote source, when a UI file has started importing response classes, or when a screen shows a spinner forever after a response shape changed.
- [`api-ok-but-ignored`](references/api-ok-but-ignored.md) — A remote write can answer "ok" and still have discarded what you sent, saying so only in a secondary field riding along with the success. Model accepted-but-discarded as its own outcome, read that field on every write, and log a discard loudly. Reach for it when a submission reports success on every call and the data never appears on the other side.
- [`unknown-not-a-valid-score`](references/unknown-not-a-valid-score.md) — A parse-failure fallback must be a sentinel outside the legal domain, or expressed in the type — never a value the success path can also produce. Expose "not known" as its own question. Use when a field means two different things depending on where it came from, when a placeholder reaches the screen, or when a consumer cannot tell absent from measured.
- [`enum-normalize-over-legacy-data`](references/enum-normalize-over-legacy-data.md) — Reading a type marker the remote source declares for itself — normalizing before every comparison because locally stored rows from older app versions hold labels the app invented, treating null as "the source did not say" rather than as a default, exposing an is-known predicate so callers branch on knowledge, and correcting old rows by write-through instead of a migration. Use when a stored type column holds several spellings, when an item is treated as the wrong kind, or before adding a database migration to fix historical values.

## Auth, retries and account state

- [`oauth-callback-not-through-nav`](references/oauth-callback-not-through-nav.md) — Deliver a returning auth callback's token straight to session state and let the login screen close itself by observing the stored session — routing the token through navigation pushes a second login screen and the post-login close peels the wrong one. Use when a browser-based login succeeds but the user is left staring at the login screen.
- [`retry-needs-backoff-and-cap`](references/retry-needs-backoff-and-cap.md) — Give every reconnect loop exponential backoff, a ceiling, a class of failures it refuses to retry, and a lifecycle gate — then give the feature a health signal, because one that fails silently stays broken for months. Use when a background connection drains the battery, when a bad credential produces an endless reconnect, or when an integration quietly stopped working.
- [`login-state-fans-out-to-settings`](references/login-state-fans-out-to-settings.md) — Logging out must reset every setting that depended on being logged in, at the logout choke point itself — otherwise a gated switch stays on for a service you are no longer authenticated to and silently no-ops forever, or errors on every tick. Use when a feature toggle is stuck on, cannot be switched off, or keeps running against a credential that is gone.
- [`nested-flag-settings-auto-disable`](references/nested-flag-settings-auto-disable.md) — A child toggle gated by a parent condition must key its auto-disable effect on the parent's current value, grey out rather than hide when the gate is closed, and be gated again at the consumer — otherwise the child sticks ON with no way for the user to clear it. Use when a settings switch is stuck on, is greyed out while reading enabled, or keeps acting after its precondition is gone.

## Realtime sessions and wire protocols

- [`monotonic-clock-offset-sync`](references/monotonic-clock-offset-sync.md) — Estimate a peer's clock offset from ping/pong round trips — take the peer's own processing time out before halving, weight each sample against the best round trip seen, insist the local time source is monotonic, and fall back to the uncorrected value while the estimate is not yet usable. Use when several devices must agree what time it is before they can agree where a stream is, when a group drifts apart on a congested network, or when a position correction jumps after the device adjusts its clock.
- [`protobuf-without-codegen-kmp`](references/protobuf-without-codegen-kmp.md) — Speak protobuf from shared Kotlin by annotating ordinary data classes with field numbers instead of generating a code layer — with the encoder setting that makes the bytes match a generated encoder, the equality override a byte-array field needs, and the conformance test that pins the equivalence. Use when a schema-driven protocol has to work on every target rather than only the JVM, when encoding a message with an absent nested field throws, or when round-trip tests pass while real peers reject the frames.
- [`borrowed-wire-protocol-discipline`](references/borrowed-wire-protocol-discipline.md) — Rules for implementing a protocol someone else defined — no renaming, no reordering, constants the schema omits read off the counterpart implementation rather than guessed, unknown message types decoded to null instead of thrown, and negotiated capabilities narrowed but never widened. Use when your client must interoperate with an implementation you do not control, when a connection opens and then never gets anywhere, or when a peer on a newer version breaks your session.
- [`websocket-session-handshake-lifecycle`](references/websocket-session-handshake-lifecycle.md) — The order a WebSocket session has to be brought up and torn down — reader started before the first message because the answer comes back through it, the handshake settled on a deferred with a timeout, the close frame sent under a non-cancellable context, and an event buffer that suspends rather than drops. Use when a socket connects but the session never becomes usable, when a deliberate disconnect leaves the peer thinking you are still there, or when clients drift out of sync after a burst of traffic.
- [`publish-a-snapshot-on-taking-the-role`](references/publish-a-snapshot-on-taking-the-role.md) — Every publisher in a shared session is edge-triggered off a change, so a participant who was already running when they took the publishing role emits nothing and the group sits in silence — publish a full snapshot on becoming the source, and again when a new member arrives. Use when a session starts empty until someone touches the transport, when a late joiner sees nothing, or when your state watchers all look correct and the group still knows nothing.