Docs menu: Error codes

Error codes

Every error from the CreditKit API has the same shape. Match on code: it never changes. error is a human-readable message that may be reworded.

Error response (HTTP 400 · JSON)
{
  "ok": false,
  "code": "UNKNOWN_ACTION",
  "error": "Unknown action "generate_imgae". Register it under Pricing ...",
  "fix": "Register the action under Pricing in the console, fix the typo, or ...",
  "docs": "https://creditkit.dev/docs/errors#UNKNOWN_ACTION"
}

The SDKs pass code, fix and docs through on every failed result. Send CreditKit-Version: 2026-11-16 to pin the API version (@creditkit/node does this for you); every response echoes the version that answered it.

Keys & auth

MISSING_PROJECT_KEY
400
Send projectKey (pk_test_... / pk_live_...) from the browser, or Authorization: Bearer sk_test_... / sk_live_... from your server.
MISSING_SECRET_KEY
401
This call is server-only. Set CREDITKIT_SECRET_KEY (sk_test_... or sk_live_...) on your server and send it as Authorization: Bearer <key>. Never ship it to the browser.
INVALID_SECRET_KEY
401
The secret key is wrong, revoked or not a secret key. Copy it again from Keys & webhooks in the CreditKit console (test and live keys are different).
KEY_PROJECT_MISMATCH
401
The secret key and projectKey belong to different projects. Use the pair shown together under Keys & webhooks.
PROJECT_NOT_FOUND
404
No project has this key. Check NEXT_PUBLIC_CREDITKIT_KEY / CREDITKIT_SECRET_KEY, and that you are not mixing test and live keys.
ORIGIN_NOT_ALLOWED
403
This site's origin isn't your project's App URL. Add it in the console (comma-separate several), or use your pk_test_ key while developing locally.
AUTH_REQUIRED
401
This project only gives credits to signed-in users. Pass the signed-in userId (with identitySignature from credits.signUser) or charge from your server with the secret key.
IDENTITY_SIGNATURE_INVALID
403
Compute identitySignature on your server with credits.signUser(userId) using the same mode (test or live) as the publishable key.
IDENTITY_ALREADY_BOUND
403
This user id or email already belongs to another user's balance in this project. Sign the other session out (CreditKit.logout()) before identifying.
UNAUTHORIZED
401
Send a valid secret key from your server, or the visitor token creditkit.js stores (X-CreditKit-Token) from the browser.
FORBIDDEN
403
This key or session is not allowed to do that. Use the project owner account or the project secret key.

Charging

INSUFFICIENT_CREDITS
402
The user doesn't have enough credits. Open the paywall in the browser (window.CreditKit.openTopUp(action)) so they can top up.
UNKNOWN_ACTION
400
Register the action under Pricing in the console, fix the typo, or pass allowDefaultFallback: true to charge the "default" action.
INVALID_ACTION_KEY
400
Action keys are 1-64 characters of letters, numbers, "_", "-", "." or ":".
INVALID_UNITS
400
units must be a whole number from 1 to 1,000,000. Round usage up before sending it.
INVALID_AMOUNT
400
amount is a whole number of credits from 1 to 100,000,000. Usually you leave it out and let the action price the charge.

Holds

INVALID_TTL
400
ttlSeconds must be from 10 to 86400. For longer jobs, pass autoExtend: true (SDK) or extend the hold periodically.
INVALID_HOLD_ACTION
400
When updating a hold, send action: "settle", "refund" or "extend".
HOLD_NOT_FOUND
404
Use the holdId returned when the credits were reserved, with a key from the same project and mode.
HOLD_NOT_PENDING
409
The hold already settled, refunded or expired. Settle it anyway to charge the run (a late settle); it can no longer be extended.
HOLD_UNAUTHORIZED
403
Settle or refund holds with the key that created them: your secret key for server holds, the visitor token for browser holds.
INVALID_USAGE
400
Report usage as a whole number ≥ 0, either actualUnits or actualAmountUsed (not both). In the SDK: reportUsage({ units }) or reportUsage({ credits }).
USAGE_REQUIRES_SECRET_KEY
403
Only your server can say how much a run used. Charge usage-priced actions with @creditkit/node (withCrashProofHold + reportUsage).

Users & balances

WALLET_MODE_MISMATCH
400
A Test Mode secret key only changes test wallets (wal_test_...) and a live key only live ones. Use the key for the mode of the customer you are adjusting.
INVALID_EXPIRY
400
expiryDays is a whole number of days from 1 to 3650. Leave it out for credits that never expire.
MISSING_TARGET
400
Say whose balance to change: send targetWalletId, targetWalletIds, userId, email, or the visitor token (X-CreditKit-Token).
INVALID_THRESHOLD
400
maxBalanceThreshold is a number of credits, 0 or more. Wallets at or below it get the grant.
MISSING_USER
400
Pass userId (your app's user id), email or walletId. Secret-key calls must say whose credits to use.
WALLET_NOT_FOUND
404
No user with that id in this project and mode. Check the userId / walletId, and that you are using the right test or live key.
INVALID_CURSOR
400
Pass the nextCursor from the previous page unchanged, or leave cursor out to start from the newest.
NO_ACTIVE_SUBSCRIPTION
400
This user has no active plan to change. Send the user to checkout to start one.

Checkout & growth

TIER_NOT_FOUND
404
Use a pack or plan id from your project (GET /api/v1/status lists them under project.tiers).
UPGRADE_PAYMENT_FAILED
402
The plan change couldn't be charged. Ask the user to update their card in the billing portal and try again.
PROMO_REQUIRED
400
Send the promo code the user typed as code (for /api/v1/growth) or promoCode (for /api/v1/checkout).
PROMO_INVALID
404
No promo code with that name exists in this project. Codes are created under Pricing in the console.
PROMO_EXPIRED
400
The code has expired. Extend it or create a new one under Pricing in the console.
PROMO_LIMIT_REACHED
400
The code hit its redemption limit. Raise the limit under Pricing in the console if you want more redemptions.
PROMO_ALREADY_REDEEMED
400
Each user can redeem a code once.
OFFER_ALREADY_REDEEMED
400
This user already used this one-time offer.
FEATURE_NOT_ENABLED
403
Turn the feature on for this project in the console (it may need the Builder or Studio plan).
INVALID_GROWTH_ACTION
400
Check the action name against the /api/v1/growth reference.

Requests

MISSING_PARAMETER
400
A required field is missing; the error message names it.
INVALID_JSON
400
Send a JSON object body with Content-Type: application/json.
INVALID_REQUEST
400
The request was malformed; the error message says what was wrong.
INVALID_API_VERSION
400
Send a CreditKit-Version the API knows (or leave the header out to use the current version).
NOT_FOUND
404
The thing you asked for does not exist in this project.
CONFLICT
409
The request conflicts with the current state; reload it and retry.
RATE_LIMITED
429
Too many requests. Wait for the Retry-After seconds, then retry with backoff.
INTERNAL_ERROR
500
Something failed on CreditKit's side. Retry with the same Idempotency-Key; if it keeps happening, contact support@creditkit.dev.