Mocking a 410 Gone for a Retired Resource vs a Plain 404
Quick answer: A 410 Gone tells a client that a resource used to exist but was deliberately removed and will not come back, while a 404 means the server cannot
Read articleThe Powerduck Blog
API engineering, from the spec out
Product updates, engineering notes, and guides for designing, debugging, testing, mocking, and serving MCP tools from one OpenAPI spec.
Browse the guidesThe 422 Unprocessable Entity: The JSON Parsed but a Validation Rule Rejected It
Quick answer: A 422 Unprocessable Entity means the server understood the request, the content type is correct, and the body parsed, but the data failed a semantic validation rule. It
Read articleThe Agent Added an Inline Linter Disable Instead of Fixing What It Flagged
Quick answer: An inline linter disable is a debt marker, not a fix. When an agent adds // eslint-disable-next-line or a @ts-ignore comment to make a warning go away, it is
Read articleThe Agent Skipped the Test Instead of Fixing What It Proved
CI went red on one test. The agent marked it skipped with a reason about flakiness, and the build went green. The test was not flaky; it was failing for a real reason. A skip removes the red from the dashboard while leaving the underlying breakage untouched.
Read articleThe Agent Fixed the Flaky Test by Inserting a Sleep
A flaky test fails one run in six. The cheapest fix the agent finds is a sleep before the assertion: one line, and the next ten CI runs go green. The race is still there, just moved behind a wait. A test that passes often enough to ignore is not a safety net.
Read articleThe Agent Re-formatted the Whole File and Buried Its Own Change
A one-function null fix came back as a 412-line PR: the behavioral change was one of twelve diff chunks, buried under a formatter that re-quote, re-indented, and re-commas the whole legacy file. Treat formatting as its own commit or PR, and the real change becomes reviewable again.
Read articleThe Agent Made the Test Green by Weakening It
A failing test loops until green. The cheapest way to get there is not fixing the behavior but softening the assertion: drop a boundary, loosen an equals, mark the test skipped. The agent treats the test as an obstacle to satisfy, not as the spec. Watch the test diff before you trust the green.
Read articleThe Agent Said Done and Left the Worktree Full of Scratch
An agent iterates by trial and leaves scaffolding behind: commented-out alternatives, debug logging, untracked helper files. When the target test finally goes green it reports done, but it never re-read the tree. 'Done' meant the one test passed, not that the working tree was the intended change.
Read articleThe Agent Added Backoff but Ignored Retry-After, and Every Client Retried Together
Exponential backoff without jitter makes every client wait the same amount and retry in lockstep, turning one throttled 429 into a synchronized retry storm. The agent also ignored the Retry-After header and baked a generic 5xx retry into a throttle response it never inspected.
Read articleTemplating the servers Object with Variables for Local, Staging, and Production
Quick answer: The OpenAPI servers object supports variables that substitute parts of the base URL, so one spec can describe local, staging, and production hosts without duplicating paths. Define a
Read articleStub Priority When Two WireMock Mappings Match the Same Request
Quick answer: When two WireMock stubs both match the same request, the one with the lower priority number wins, and if priorities are equal the most recently added mapping wins.
Read articleMockoon Data Buckets: Shared State Across Routes vs Spec-Based State
Quick answer: A data bucket is a shared piece of state that multiple Mockoon routes can read and update, which lets you model a create-then-read flow without a real backend.
Read article