Errors
Clowk SDK errors explained, such as ConfigurationError, InvalidStateError and InvalidTokenError, plus HTTP status codes and how to fix and handle each one.
Error hierarchy
All Clowk errors extend from ClowkError:
ClowkError
├── ConfigurationError
├── InvalidStateError
└── InvalidTokenErrorConfigurationError
Thrown when the SDK is not configured correctly.
ConfigurationError: Missing publishableKeyFix: Call configure() with your keys before using any Clowk function, or set the environment variables.
InvalidStateError
Thrown when the OAuth state parameter doesn't match.
InvalidStateError: State mismatchFix: This usually means the user's session expired during the OAuth flow. Ask them to try signing in again.
InvalidTokenError
Thrown when JWT verification fails.
InvalidTokenError: Token expired
InvalidTokenError: Invalid signature
InvalidTokenError: Invalid issuerFix:
- Token expired — the JWT has passed its expiration time. The user needs to sign in again.
- Invalid signature — the token was signed with a different secret key. Check that your
secretKeymatches the one in your Clowk dashboard. - Invalid issuer — the token was issued by a different Clowk project.
HTTP error codes
| Code | Meaning |
|---|---|
401 | Unauthorized — missing or invalid token |
403 | Forbidden — valid token but insufficient permissions |
429 | Too Many Requests — rate limit exceeded |
500 | Internal Server Error — unexpected error on Clowk's side |
Handling errors
import { ClowkError, InvalidTokenError } from '@clowk/core'
try {
const user = await verifyToken(token)
} catch (err) {
if (err instanceof InvalidTokenError) {
// Token expired or invalid — redirect to sign-in
} else if (err instanceof ClowkError) {
// Other Clowk error
}
}Contributing
How to contribute to Clowk: open pull requests to the SDKs and docs, build a community SDK for a new framework, and report bugs or request features.
@clowk/core
@clowk/core is the runtime-agnostic base for every Clowk JavaScript SDK: config, errors, a fetch HTTP client, API client and JWT verification.