agent generated the client from the provider's OpenAPI spec - the spec's examples were wrong and every happy-path...

TL;DR

Stop trusting the spec's examples and validate the client against the live API instead. The provider's examples were wrong, so the generated happy path encodes those mistakes.

Treat the spec as a schema sketch: field names and types are usually right, but example values and request shapes need a live probe before you believe them.

Verbatim query

agent generated the client from the provider's OpenAPI spec  -  the spec's examples were wrong and every happy-path call failed

Steps

1. Reproduce with the generated happy path

Run the client's simplest documented call and capture the full request and response. Note exactly which part of the request the API rejects. Expected: The simplest call fails and the error names the specific bad part.

1. Compare the spec example against reality

Open the spec's example for that endpoint and diff it against what actually works. Send hand-built variants until one succeeds, changing one thing at a time. Expected: You have a working request shape and can point to where the spec example diverges.

1. Correct the client to the working shape

Patch the generated code or the request templates to match the working shape. Do not wait for the provider to fix their spec. Expected: The happy path now succeeds against the live API.

1. Report the spec bug to the provider

File an issue or email support with the spec section, the example, and your working request. Keep it factual: wrong example, not a rant. Expected: The provider acknowledges the bad example or updates the spec.

1. Add live contract tests

Write tests that run the happy path against the sandbox on every regen. Assert on status and key response fields, not on matching the spec example. Expected: A future wrong example fails the contract test instead of shipping broken code.

Use this when

• Generated code follows the spec but the simplest real call fails
• The spec's example request 400s while a hand-built variant succeeds
• Every happy-path call fails in the same way across endpoints

Not for this skill when

• The spec is correct and the agent misread it - reread before blaming the spec
• Only edge cases fail - that is incomplete spec coverage, not wrong examples
• Calls fail with auth errors - the example may use a placeholder credential, which is a different problem

Variant phrasings

spec examples are wrong

Spec examples are marketing copy that nobody runs; the schema is usually right and the examples are usually stale.

generated from bad spec examples

A client generated from wrong examples encodes the provider's mistake as your bug.

happy path fails against real API

When the simplest call fails, suspect the spec example before suspecting your code.

Why it happens

Nobody runs spec examples as tests. The schema gets validated by tooling, but the example blocks are free text that rots: the API changed, the example did not, and the generator dutifully turns the rotten example into your client's default behavior. The spec is still useful for types and field names, but examples are claims, not evidence - only a live call is evidence.

Edge cases

• Some providers publish a corrected spec at a different URL than the docs link - check both
• Examples in the docs prose can contradict examples in the spec; when they disagree, the live API is the tiebreaker
• If the provider never fixes the spec, keep your corrected request templates in version control as the real source of truth

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_GBuj2OigHYcKuXxJv4zSeQ