Every error returned by the SDK includes a code, message, suggestion, and docs_url. Some errors also include a fix_command you can copy-paste.
token/expired
| Field | Value |
|---|
| Message | Token has expired |
| Suggestion | Request a new access token via refresh token endpoint |
token/invalid_signature
| Field | Value |
|---|
| Message | Token signature verification failed |
| Suggestion | Ensure the token was issued by Rakomi and has not been tampered with |
| Field | Value |
|---|
| Message | Token is not a valid JWT format |
| Suggestion | Ensure you are passing a complete JWT string (header.payload.signature) |
token/invalid_algorithm
| Field | Value |
|---|
| Message | Unsupported algorithm. Only RS256 is allowed |
| Suggestion | Rakomi tokens use RS256. Do not attempt to use HS256 or other algorithms |
token/missing_claims
| Field | Value |
|---|
| Message | Required claims missing (sub, tenant_id, email, sid, iss, aud, exp, iat, jti) |
| Suggestion | Ensure the token was issued by Rakomi login/refresh endpoints |
token/invalid_issuer
| Field | Value |
|---|
| Message | Token issuer mismatch |
| Suggestion | Token must be issued by rakomi.com. Verify you are using the correct environment |
token/not_yet_valid
| Field | Value |
|---|
| Message | Token nbf (not before) is in the future |
| Suggestion | Check system clock synchronization or increase clockTolerance in SDK config |
| Fix command | new RakomiClient({ apiKey: "...", clockTolerance: 60 }) |
token/missing
| Field | Value |
|---|
| Message | Authorization header with Bearer token is required |
| Suggestion | Include an Authorization header: Bearer <token> |
token/internal_error
| Field | Value |
|---|
| Message | An internal error occurred during token verification |
| Suggestion | This is unexpected. Please retry or contact support |
jwks/fetch_failed
| Field | Value |
|---|
| Message | Failed to fetch JWKS |
| Suggestion | Check network connectivity and that baseUrl is correct |
| Fix command | curl https://api.rakomi.com/.well-known/jwks.json |
jwks/no_matching_key
| Field | Value |
|---|
| Message | No key in JWKS matches token kid |
| Suggestion | The signing key may have been rotated. This is transient during key rotation — retry in a few seconds |
jwks/invalid_response
| Field | Value |
|---|
| Message | JWKS response is not a valid JSON Web Key Set |
| Suggestion | Ensure baseUrl points to a valid Rakomi instance |
webhook/timestamp_expired
| Field | Value |
|---|
| Message | Webhook timestamp is too old (exceeds tolerance) |
| Suggestion | Ensure your server clock is synchronized. The webhook may be a replay attack |
webhook/invalid_signature
| Field | Value |
|---|
| Message | Webhook HMAC signature verification failed |
| Suggestion | Verify the webhook secret matches the one in your Rakomi dashboard |
| Field | Value |
|---|
| Message | Required webhook headers missing (X-Rakomi-Signature, X-Rakomi-Timestamp, X-Rakomi-Delivery-Id) |
| Suggestion | Ensure you are passing the raw request headers to verifyWebhook() |
webhook/invalid_body
| Field | Value |
|---|
| Message | Webhook body is not valid JSON |
| Suggestion | Use express.raw() or express.text() middleware to preserve the raw body for webhook routes |
config/missing_api_key
| Field | Value |
|---|
| Message | apiKey is required |
| Suggestion | Pass your API key when creating the client |
| Fix command | new RakomiClient({ apiKey: "akm_live_xxx" }) |
config/invalid_base_url
| Field | Value |
|---|
| Message | baseUrl must be a valid HTTPS URL |
| Suggestion | Use a full URL including protocol, e.g., https://api.rakomi.com |
config/missing_webhook_secret
| Field | Value |
|---|
| Message | webhookSecret is required for webhook verification |
| Suggestion | Pass your webhook signing key in config |
| Fix command | new RakomiClient({ apiKey: "...", webhookSecret: "whsec_xxx" }) |
These errors are returned by the Rakomi API (not the SDK):
auth/token_expired
| Field | Value |
|---|
| Message | Access token has expired |
| Suggestion | Use the refresh token to obtain a new access token |
auth/invalid_credentials
| Field | Value |
|---|
| Message | Invalid email or password |
| Suggestion | Check your credentials and try again |
auth/email_not_verified
| Field | Value |
|---|
| Message | Email address has not been verified |
| Suggestion | Check your inbox for the verification email or request a new one |