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 |
tenant/social_signup_blocked_minor_protection
| Field | Value |
|---|
| Message | Self-service sign-up via this channel is not available for this tenant. |
| Suggestion | Contact your tenant administrator for other provisioning options, or direct the user to the tenant’s own registration form, which collects the information minor protection requires. |
Returned with HTTP 403 when a tenant has minor protection
enabled and a stranger attempts to create a new account through a social provider, the EUDI
wallet channel, or by claiming an anonymous session — none of which collect the date of birth
minor protection requires. It never applies to an existing user signing in or linking an
additional provider to an account they already have.
