Errors and troubleshooting

Error Reference

{
  "status": "error",
  "code": "ERROR_CODE",
  "message": "Description",
  "retryable": true,
  "retryAfter": "ISO8601",
  "cooldownSeconds": 60,
  "details": {}
}

OTP dispatch responses

These dispatch responses apply to request-otp and resend-otp; OTP_NOT_REQUESTED also applies to verify-otp. The two 409 codes are returned when a send for that attempt is already in flight, or when the outcome of an earlier send for it is unknown. For resend-otp, the one resend is claimed just before dispatch, after the endpoint's own checks: your one resend is already consumed when a dispatch conflict is returned, so a retry returns 429 RESEND_LIMIT_EXCEEDED. Earlier endpoint checks can also return a different error. Dev-mode test pairs never return these 409s; they send no real code.

{
  "status": "error",
  "code": "OTP_DISPATCH_IN_PROGRESS",
  "message": "Your verification code is still being sent. Please wait a few seconds and try again.",
  "retryable": true,
  "retryAfterSeconds": 3,
  "reason": "dispatch_in_progress"
}

{
  "status": "error",
  "code": "OTP_DISPATCH_OUTCOME_UNKNOWN",
  "message": "We could not confirm that your code was sent. Please start a new verification.",
  "retryable": false,
  "reason": "dispatch_outcome_unknown",
  "certainty": "unknown",
  "redirectUrl": "https://merchant.example/auth/callback?status=failed&error=OTP_DISPATCH_OUTCOME_UNKNOWN&transactionId=example-transaction&attemptId=example-attempt&timestamp=2026-10-06T12%3A00%3A00.000Z"
}

V2 Widget errors reach you by four different routes, and the route decides the shape of the response body — so check which table a code is in before writing a handler for it. Shared-handler responses carry retryable and action. Endpoint-handler responses list their endpoint-specific body fields. Middleware responses carry the fields shown in their row. Dual-path codes arrive both ways depending on the endpoint.

Shared error-handler responses

Returned by the passkey SDK endpoints and by middleware that hands the error to the shared handler. These bodies carry retryable and action alongside the code.

On create-attempt, authenticateCreateAttempt runs before the controller. Its MISSING_REQUIRED_FIELDS, INVALID_SIGNATURE, SIGNATURE_EXPIRED responses use status, code, message, retryable, action.

Error-handler fallbacks

Endpoint-handler responses

The widget endpoints choose the status in the handler itself. These rows list the fields emitted by each endpoint. Some handlers add retryable or conditional redirect/quota fields.

The request-otp, verify-otp and resend-otp responses are answered to the hosted widget, which handles most of them itself, such as the duplicate-send and channel-choice rows. They are listed here so the contract is complete.

Direct error responses (rate limits, circuit breaker, bans)

Rate-limit and circuit-breaker rows are answered by middleware, before the endpoint handler runs at all — so they pre-empt that endpoint's own rows. The zero-verify ban is different: IDENTITY_TEMPORARILY_BLOCKED is returned by the request-otp and resend-otp handlers themselves, after most of their other checks — so an earlier error always wins over the ban. The exact order is below.

request-otp checks, in order: required fields, attempt lookup, attempt expiry, the stored channel (CHANNEL_NOT_OFFERED, only when a channel is sent), the live test-pair/widget load, the idempotent already-requested return, captcha state, the account lookup, then the ban. After the ban come the channel quota check (only when a channel is sent, and not for test pairs), and then every transaction and activation error. The idempotent step is the one worth planning for: a repeat of a request that already succeeded returns that success, so a caller retrying after a dropped response gets the original result rather than CAPTCHA_NOT_VERIFIED.

resend-otp has no captcha step. It checks required fields, attempt lookup, whether an OTP was requested at all, the live test pair, the stored channel, the transaction lookup and its ownership, transaction expiry, the ban, channel quota (when a channel is chosen, except for test pairs), then the resend claim just before dispatch.

The rows list the fields available on each response. Where present, retryAfter is an ISO timestamp and cooldownSeconds the equivalent in seconds. Wait for that schedule rather than retrying on a fixed interval.

Dual-path errors

Advanced Features

Bring Your Own OTP

If you want to generate your own OTP codes, pass a custom otp parameter:

const response = await axios.post(
  'https://api.akedly.io/api/v1/widget-sdk/create-attempt',
  {
    apiKey: AKEDLY_API_KEY,
    publicKey: WIDGET_PUBLIC_KEY,
    signature,
    timestamp,
    verificationAddress: { phoneNumber: '+201234567890' },
    otp: '123456', // Your custom OTP (4, 5 or 6 digits)
  },
)

Troubleshooting

INVALID_SIGNATURE Error

Common causes:

• Incorrect HMAC algorithm (must be SHA256)
• Wrong JSON key order in signature message
• Extra spaces in JSON string
• Widget secret is incorrect
• Timestamp is outside the 60-second window (stale or ahead of server time)

Solutions:

• Verify you're using HMAC-SHA256
• Ensure the message format matches the attempt. A phone attempt signs JSON.stringify({ apiKey, publicKey, timestamp, phoneNumber }). An email-only attempt signs JSON.stringify({ apiKey, publicKey, timestamp }) — phoneNumber is omitted entirely, not sent as null or "", because the server builds the same string from an absent value and JSON.stringify drops an undefined property. Adding the key back is the usual cause of an email-only signature mismatch.
• Check your widget secret matches the dashboard
• Synchronize server clock with NTP — a clock 60+ seconds fast fails as hard as one that is slow
• Generate a fresh timestamp and signature per request; never queue or replay a signed payload

Iframe Shows Blank Screen

Common causes:

• Invalid or malformed attemptId in URL
• Attempt has expired (5-minute lifetime)
• Parent page not served over HTTPS
• Browser blocking mixed content
• sandbox attribute without allow-same-origin

Solutions:

• Check browser console for errors
• Verify iframeUrl contains a valid attemptId
• Ensure parent page uses HTTPS in production
• Confirm attempt hasn't expired
• If the iframe has a sandbox attribute, include allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox

Widget Shows "Turn on cookies to continue"

Common causes:

• The browser or OS blocks cookies, for example Safari with "Block All Cookies" on
• Storage is blocked for the embedded frame only
• Android WebView without DOM storage

Solutions:

• Have the user follow the on-screen steps, then tap "I’ve turned it on — try again"
• Use "Open in a new tab", where the browser is more likely to allow storage
• On native apps, open the widget in a system browser instead of a WebView
• In an iframe, add clipboard-write to allow so Copy link works, and check the frame settings — see When the browser blocks cookies

PIPELINE_NOT_CONFIGURED Error

Solution:

• Go to Authentication → Setup → Widgets → [Your Widget]
• Edit the widget and open the Pipeline section
• Select a pipeline from the dropdown
• Save changes

OTP Not Received

Common causes:

• Phone number format is incorrect
• Rate limit exceeded for phone number
• Pipeline verification methods not configured

Solutions:

• Ensure phone number uses E.164 format with country code (e.g., +201234567890)
• Check rate limit status in dashboard analytics
• Verify pipeline has at least one verification method enabled