If Swagger Works but Your SDK Fails, Your SDK Is Lying

Source: Dev.to

The Setup

I was building a feature‑flag / runtime‑config service (just a fun thing to do during the holidays).
The idea was simple:

• Backend exposes config values per environment.
• SDK fetches them at runtime.
• Same token, same environment, same key.

Swagger UI worked perfectly, but the SDK threw:

ConfigNotFoundError: config not found in environment 'development'

Swagger wasn’t lying—it showed the request, the headers, the resolved environment, and the correct response.

The problem turned out to be a mismatched route:

• Backend exposed this route:

  GET /api/v1/sdk/configs/{key}

• My SDK was building URLs like this:

  /api/v1/config/{key}

The SDK silently returned a clean 404 with no exception or warning, leading to hours of wasted debugging.

Lesson

• Your SDK must match your backend routes character for character.
• If you need a reminder, set one—otherwise you’ll spend days chasing phantom bugs.

Additional Gotcha

Configs were stored as:

FEATURE_CHECKOUT_ENABLED

but SDK users could pass:

"feature_checkout_enabled"

This caused:

• Cache misses
• False “not found” errors
• Inconsistent results

Fix: Normalize input once and enforce it everywhere (before API calls, before caching, before comparisons).

What This Experience Taught Me

• Swagger is your contract.
• SDKs can lie by omission.
• Route mismatches are silent killers.
• Normalization prevents phantom bugs.
• If Swagger works, your backend is innocent.
• Swagger first. SDK second. Database last.