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. |