Test vs Live Keys

Test keys are for trying the API: a one-time allowance of 250 requests per account, never billed. Live keys run production against your plan's monthly quota. The exact rules, including which statuses count.

The short version

	`tk_test_`	`tk_live_`
Conversion behavior	Identical — full engine, real results	Identical — full engine, real results
Draws from	One-time 250-request allowance — per account, shared by all your test keys, never resets	Your plan's monthly quota (Free: 1,000/month)
When the pool/quota is spent	429 on every plan — create a live key	Free: 429 until the month resets; paid plans: never blocked, overage is metered
Billed (Stripe)	Never	Yes, on billable statuses
Intended use	Evaluating the API, verifying your integration parses our output	Everything else, including development at volume

Test keys are not a sandbox with fake output — they run the same conversion engine and return real results. That's exactly why the allowance is deliberately small and one-time: a credential that returns production-grade conversions for free would otherwise just be a free live key. 250 requests is enough to evaluate every endpoint and wire up your integration; sustained development and CI belong on a live key.

The one-time test allowance

250 requests per account, lifetime. All your test keys (and test OAuth clients) draw from the same pool. Creating another test key does not grant another 250.
It never resets. There is no monthly refill; X-Quota-Limit: 250 and a shrinking X-Quota-Remaining on every test-key response show where you stand, as do the test_quota/test_used/test_remaining fields of GET /v1/usage.
Same on every plan. Upgrading does not refill the pool — paid plans' overage applies to live keys only.
What counts: responses where the engine did real work — 2xx and content-level 400/422. Auth failures, 429s, 5xxs, and idempotent replays never count.
When it's spent: metered routes answer quota-exceeded 429 with a detail pointing you at live keys (and no reset date — there isn't one). Batch counts too: enqueues are pre-checked against the pool and each processed item draws from it.

Which responses bill (live keys)

Status	Bills / counts?	Why
`2xx`	Yes	Successful conversion/normalization/validation
`400 invalid-input`	Yes	The engine parsed and rejected your message — that's work
`422` (unsupported-format, charset, ...)	Yes	Same — content-level rejection required processing
`401` / `403` / `404` / `409` / `413` / `429`	No	Rejected before the engine ran
`5xx`	No	Our failure, never yours
Idempotent replays	No	Cached responses are free

The same status table governs what counts against the test allowance — a malformed message consumes a test request too.

Recommended setup

Evaluate with a test key: hit /v1/formats, convert representative samples of each message type you handle, inspect the warnings. 250 requests covers this comfortably.
Develop and run on a live key. On the Free plan the first 1,000 conversions each month cost nothing, so "live" does not mean "paying" — it means metered.
Watch X-Quota-Remaining on responses — it always reflects the pool the key you're using draws from. See Rate Limits & Quotas.

Was this page helpful?