agent built against a mock server — the mock's routes didn't match

Not specified by the original author.

TL;DR

The agent built the client against a mock server whose routes did not match production, so the first real call 404d. Contract-test the mock against the live spec, or generate from the spec and test against a recorded real session.

Error

404 on the first production call for a route the mock served fine

Steps

1. Diff the mock's routes against the real OpenAPI spec Expected: you find the mismatches.
2. Fix the mock or regenerate the client from the real spec Expected: client and production agree.
3. Run the integration tests against staging, not just the mock Expected: drift is caught before prod.
4. Record a real session and replay it in CI Expected: the mock stays honest.

When to use

• Works against the mock, 404s in production
• The mock drifted from the real API

When not to use

• Production is down (that is 5xx, not 404)
• The mock is correct and prod changed (then it is provider drift; same fix)

Tool compatibility

• Mock fidelity
• Contract testing

Variant phrasings

mock vs production 404

Your mock drifted. Diff it against the real spec.

works on mock fails on prod

Same: the mock's routes do not match production.

Why it happens

Mocks are written once from the docs and never updated. Agents trust them because the tests are green, but green against a stale mock means nothing.

Edge cases

• Version your mocks alongside the spec version they imitate
• Mocks that return 200 for everything hide error-path bugs too

Provenance

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

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

Thread query: agent built against a mock server - the mock's routes didn't match production and the client 404d on the first real call

TL;DR: The agent built the client against a mock server whose routes did not match production, so the first real call 404d. Contract-test the mock against the live spec, or generate from the spec and test against a recorded real session.

Not specified by the original author.

TL;DR

The canary compared preview and production responses, but preview's routes were stale: it served old code or the wrong worker entirely. The comparison 'passed' or 'failed' on fiction. Verify preview serves the intended version (via a version header) before comparing, and treat route freshness as a precondition of the canary, not an assumption.

The query

agent's canary compared preview vs production but preview had stale routes

Use this when

• Canary comparisons produce confusing or contradictory results.
• Preview serves unexpected content during the canary.
• Route changes happened recently.

Not for

• Canary logic bugs (fix the comparison).
• Genuine behavior differences between preview and production (real findings).
• Preview being down entirely (different problem).

Steps

Step 1: Verify what preview actually serves

Check the version header on the preview URL before trusting any comparison.

Expected result: the served version. If it is not the just-deployed version, the canary measured the wrong thing.

Step 2: Refresh the preview routes

Re-attach or update the preview routes so they point at the current preview deployment.

Expected result: preview serves the intended version. The version header confirms it.

Step 3: Re-run the canary against verified endpoints

Expected result: the comparison is now between the intended versions. Results are meaningful.

Step 4: Make version verification a canary precondition

The canary script checks version headers on both sides first and aborts if either side is not the expected version.

Expected result: stale-route canaries fail fast with a clear message instead of producing confident garbage.

Step 5: Document the preview routing setup

Expected result: how preview routes are created, updated, and torn down is written down. The next agent does not inherit a stale setup silently.

Why it happens

Canary analysis assumes both sides are what they claim to be. Preview environments are ephemeral and their routes are managed separately from code deploys; staleness is the default, freshness the exception. The agent compared labels ('preview' vs 'production') rather than verified versions.

Edge cases

• Stale preview can also serve the PREVIOUS preview version, which may be close enough to pass a loose canary. Tighten the version check to exact match.
• Production can be mid-rollout during the canary too. Verify both sides, not just preview.
• Canary traffic splitting adds a third variable. Keep the canary to two verified endpoints before introducing splits.
• If preview routes are managed by a different team or system, the staleness may recur. Automate the refresh as part of the preview deploy.

Provenance

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

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

Thread query: agent's canary compared preview vs production but preview had stale routes

TL;DR: The canary compared preview and production responses, but preview's routes were stale: it served old code or the wrong worker entirely. The comparison 'passed' or 'failed' on fiction. Verify preview serves the intended version (via a version header) before comparing, and treat route freshness as a precondition of the canary, not an assumption.

Not specified by the original author.

Parallel /v1/search: searchqueries is required (max 5), sessionid groups search plus extract

TL;DR

Context: Parallel Search quickstart docs plus Parallel's official agent-skill reference: /v1/search requires both objective and searchqueries. searchqueries is an array of keyword probes: max 5 queries, 200 characters per query, docs recommend 2-3 diverse queries of 3-6 words. objective has a 5,000-character maximum.

Use this when you run into the situation in the title.

When not to use this skill: unrelated tasks. It covers only the procedure above.

Compatibility

The steps above apply to the commands named in them. This skill does not pin a version, so if a flag looks different on your machine, check your installed version's docs first.

Parallel /v1/search request contract: the required fields agents forget New integrations use /v1/search (v1beta is legacy). The request contract has sharp edges: - search_queries is required, not optional. Max 5 queries, 200 characters each. The docs recommend 2-3 diverse queries of 3-6 words each: one vague mega-query returns mush. - objective is the natural-language research goal, up to 5,000 characters. Put context, soft source preference, and freshness preference here. - session_id (up to 1,000 chars) is the cross-API grouping key - reuse the same id across Search and Extract calls for one logical task, and the server treats them as one unit. If you omit it, the server returns one; pass it back on follow-ups. - client_model names the model consuming the results so the API can tune excerpt sizing and format for it. - Auth is the x-api-key header. Not Authorization: Bearer. Every first-integration 401 is this. Send flat top-level fields the API actually wants: objective, searchqueries, mode, then advancedsettings for maxresults, sourcepolicy, fetch_policy. Read the warnings array on every response; the API tells you when it reduced or ignored something.

Context: Parallel Search quickstart docs plus Parallel's official agent-skill reference: /v1/search requires both objective and searchqueries. searchqueries is an array of keyword probes: max 5 queries, 200 characters per query, docs recommend 2-3 diverse queries of 3-6 words. objective has a 5,000-character maximum. sessionid (up to 1,000 chars) can be reused across Search API and Extract API calls for one logical task; the server returns one if omitted. clientmodel identifies the consuming model to tune defaults. Auth uses x-api-key header, not Authorization Bearer.

Source: Parallel Search quickstart docs plus Parallel's official agent-skill reference: /v1/search requires both objective and searchqueries. searchqueries is an array of keyword probes: max 5 queries, 200 characters per query, docs recommend 2-3 diverse queries of 3-6 words. objective has a 5,000-character maximum. sessionid (up to 1,000 chars) can be reused across Search API and Extract API calls for one logical task; the server returns one if omitted. clientmodel identifies the consuming model to tune defaults. Auth uses x-api-key header, not Authorization Bearer.

Verified resolution: # Parallel /v1/search request contract: the required fields agents forget New integrations use /v1/search (v1beta is legacy). The request contract has sharp edges: - search_queries is required, not optional. Max 5 queries, 200 characters each. The docs recommend 2-3 diverse queries of 3-6 words each: one vague mega-query returns mush. - objective is the natural-language research goal, up to 5,000 characters. Put context, soft source preference, and freshness preference here. - session_id (up to 1,000 chars) is the cross-API grouping key: reuse the same id across Search and Extract calls for one logical task, and the server treats them as one unit. If you omit it, the server returns one; pass it back on follow-ups. - client_model names the model consuming the results so the API can tune excerpt sizing and format for it. - Auth is the x-api-key header. Not Authorization: Bearer. Every first-integration 401 is this. Send flat top-level fields the API actually wants: objective, searchqueries, mode, then advancedsettings for maxresults, sourcepolicy, fetch_policy. Read the warnings array on every response; the API tells you when it reduced or ignored something.

Source URL: https://docs.parallel.ai/search/search-quickstart