SDK Error Reference

The SDK validates your API key synchronously, at init(), before any network call — so a bad key fails loudly at startup instead of silently dropping data later. All five errors below are instances of TrasysAuthError, and every error message the SDK prints includes a link straight back to the matching section on this page.

Missing Key

Code: MISSING_KEY

Thrown when apiKey is empty, missing, or whitespace-only — no apiKey was passed to createSdk()/new trasys() and TRASYS_API_KEY isn't set in the environment.

Set TRASYS_API_KEY in your environment or pass apiKey in the config.

// Either of these fixes it:
createSdk({ apiKey: process.env.TRASYS_API_KEY, service: 'my-service' });

# Or set the env var directly
export TRASYS_API_KEY=sk_live_...

Invalid Key Format

Code: INVALID_KEY_FORMAT

Thrown in two cases:

• The key doesn't start with sk_live_ (production) or sk_test_ (non-production)
• The key is shorter than 40 characters (a truncated copy-paste is the usual cause)

API keys must start with "sk_live_" (production) or "sk_test_" (non-production). Get your key from https://app.trasys.dev/settings/api-keys

The error message includes the first 12 characters of what the SDK actually received, so you can tell at a glance whether the wrong variable got passed in.

Env Mismatch

Code: ENV_MISMATCH

Thrown when environment resolves to production/prod and the key starts with sk_test_. This is a hard error, not a warning — a test key in production means your production traffic would be recorded against a test account.

You are using a test key (sk_test_) in a production environment. Use a live key (sk_live_) in production.

createSdk({
  apiKey:      process.env.TRASYS_API_KEY, // must be sk_live_... here
  environment: 'production',
});

Key Revoked

Code: KEY_REVOKED

Thrown when the background key check against the ingest service (POST /v1/ingest/validate) returns 401, meaning the key has been revoked on the Trasys side.

Your API key has been revoked. Generate a new key at https://app.trasys.dev/settings/api-keys

This check runs asynchronously after init() returns, so the behavior depends on environment (see API key validation):

Account Suspended

Code: ACCOUNT_SUSPENDED

Thrown when the same background key check returns 403 — your account is suspended or over its data quota, independent of whether the key itself is valid.

Your Trasys account is suspended or over quota. Check your account status at https://app.trasys.dev

Same dev-vs-production behavior as Key Revoked above: crashes non-production processes immediately, opens a silent circuit in production.

Configuration errors

Separately from the five TrasysAuthError codes above, createSdk()/new trasys() validates your entire config object with Zod before anything else runs. If any field fails validation, you get every problem at once, not just the first one:

Error: [@trasys/sdk] Invalid configuration:
  • sampling.default: Number must be less than or equal to 1
  • ai.maxContentLength: Expected number, received string

Fix every listed field and restart — there's no partial-apply, the SDK won't start with an invalid config.

Skipping validation

For local development or CI, you can bypass both the format check and the network check entirely:

export TRASYS_SKIP_KEY_VALIDATION=true

Next steps

• Installation & Setup — full API key validation flow and environment variables
• Transport — what happens to buffered events when the network is down, separate from an invalid key
• Authentication (Public API) — the same API key is used for the read-only Public API