Evidence-based errors and explicitly approved examples.

Pro and Business Owners can opt in per key. Status and explicit validation fields guide correction; raw error inputs and credentials do not become examples.

Enable hints per key

Open Gateway as an Owner and enable Agent-friendly errors on a workspace access key. Both native and engine proxy paths retain upstream status, use bounded structured validation fields and preserve successful/SSE responses. Errors are limited to 64 KB and ten seconds. No renamed field, endpoint or OAuth refresh URL is guessed; the Gateway does not retry.

Approve trusted format examples

In Trusted format examples, select a key, supply a bounded scalar JSON Schema and explicitly approve non-sensitive synthetic fixtures. This approval is separate from the hints toggle. Only exact fields identified by a 400/422 response receive expected constraints and your explicit example, labeled owner-approved-schema with a fingerprint. A zip_code error is never silently renamed to postal_code. Unknown/unapproved fields get no invented example.

{
  "type": "object",
  "properties": {
    "zip_code": {
      "type": "string",
      "pattern": "^[0-9]{5}$",
      "examples": [
        "10115"
      ]
    },
    "max_tokens": {
      "type": "integer",
      "minimum": 1,
      "examples": [
        128
      ]
    }
  }
}

This is a synthetic schema illustration, not proof that a particular provider accepts these fields. Approval checks every supplied example against the supported constraints. Limits: 32 KB, 100 scalar fields, four nested object levels, at most three examples per field. Supported types are string/integer/number/boolean/null, bounded enum/const, numeric/string bounds, limited anchored character-class patterns and email/UUID/date/UTC date-time formats. Sensitive credential fields, common credential-like values, arbitrary regex, references/composition and unsupported keywords are rejected. Email fixtures use reserved example domains. Owners must still ensure values contain no real secrets or personal data.

Storage and privacy

Approved schema fixtures persist privately per key with Owner/date/fingerprint, and can be removed after downgrade. Other workspaces cannot change them. Telemetry stores only the latest timestamp, status, field count, duration and Retry-After presence. Audits omit example values. Known credentials are filtered from enriched error fields/headers; no failing request value is used as a sample. Synthetic previews make no provider request.

Controlled local evaluation

npm run eval:gateway-hints
npm run eval:gateway-hints:postgres
npm run test:postgres

The evaluation uses real loopback HTTP for both Gateway paths and a synthetic provider, with identical approved schemas in both cohorts and only the toggle changed. A deterministic fixture client may make one explicitly corrected validation request; it is not an LLM and never retries auth/rate-limit/unknown-outcome errors or guesses unknown fields. Reports include recovery counts and warmed, alternating before/after median/p95 timings through auth, billing, storage, provider HTTP and telemetry. The PostgreSQL harness is disposable and never reads the production database or .env. Local budget results are not a production SLA, real-assistant retry improvement, customer metric or external acceptance.