Test mode

Use vk_test_... keys to exercise the same Vorlek tool routes, middleware, SDKs, and MCP flows without calling SendGrid, Mailchimp, or Klaviyo.

Test traffic is isolated. Test keys use separate quota, rate-limit, and circuit-breaker buckets. Synthetic failures do not affect live provider traffic.

What changes with a test key

Surface	Behavior
Authentication	`vk_test_...` authenticates like a live key and is scoped to the same account.
Middleware	Auth, idempotency, validation, quota, rate-limit, and circuit checks still run.
Provider calls	Adapters return deterministic fixtures. Provider credentials are not decrypted and no upstream HTTP request is made.
Envelope	Success and error responses include `meta.test_mode: true`.
Quota	Test calls use the test quota counter, not the live operation quota.

Outcome header

Add X-Vorlek-Test-Outcome to force common response paths. Live keys ignore this header.

Header value	HTTP	Error code	Use it for
`success` or omitted	200	n/a	Happy-path SDK, MCP, and agent wiring.
`rate_limited`	429	`RATE_LIMITED`	Retry-after handling.
`provider_unavailable`	503	`PROVIDER_UNAVAILABLE`	Transient provider outage handling.
`invalid_params`	400	`INVALID_PARAMS`	Validation and repair prompts.
`tool_not_supported`	501	`TOOL_NOT_SUPPORTED`	Tool/provider fallback logic.
`provider_failed`	502	`PROVIDER_FAILED`	Terminal provider-fault handling and circuit tests.

Example retry-path probe

curl -X POST https://api.vorlek.com/v1/tools/upsert_contact \
  -H "Authorization: Bearer vk_test_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 01HV8K5K7JJZ7JWQ9X0F7G8Q3A" \
  -H "X-Vorlek-Test-Outcome: rate_limited" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "sendgrid",
    "email": "retry-path@example.com"
  }'

The response is the normal Vorlek error envelope, including meta.test_mode: true and retry metadata, so production retry code can run unchanged.

Circuit-breaker testing

Repeated provider_failed or unavailable outcomes can trip the test circuit bucket for the account/provider pair. That lets you verify CIRCUIT_OPEN behavior without degrading live SendGrid, Mailchimp, or Klaviyo traffic.

Keep test and live keys separate. Test mode is built for CI, agent evals, and prompt development. Switch to vk_live_... only when you intend to mutate real provider data.

Related references

Quickstart — signup and first tool call.
Error codes — categories, retry semantics, and recovery actions.
Python SDK and TypeScript SDK — client behavior around meta.test_mode.
SKILL.md — machine-readable agent contract.