DocumentationHosted Experience

Troubleshooting

Use this page when a Hosted Experience URL cannot be created, cannot be opened, or does not behave as expected in your app.

The API Returns 401

Likely causes:

  • missing Authorization header
  • API key is invalid or revoked
  • test key is being used against live, or live key is being used against test
  • back-end is calling the wrong platform base URL

Fix:

  • send Authorization: Bearer PLATFORM_API_KEY
  • verify the back-end environment variables
  • confirm the platform base URL with Aarthik Labs
  • rotate the key if it may have been exposed

The API Returns 400

Likely causes:

  • borrowerProviderID is missing or empty
  • journeyType is not valid
  • profile.contactNumber is missing for Gold Loan
  • goldLoan was sent without journeyType: "GOLD_LOAN"
  • a field value does not match the expected format

Fix:

  • send a non-empty borrowerProviderID
  • use PERSONAL_LOAN or GOLD_LOAN for journeyType
  • send profile.contactNumber for Gold Loan
  • use selfEmployed for self-employed borrowers
  • check the request examples in the Request & Prefill Model page

Product Entry Point Is Visible But URL Creation Fails

Likely causes:

  • the product is disabled for the API key scope
  • the front-end is showing stale configuration
  • the wrong API key is being used

Fix:

  • call GET /api/lab/features from your back-end
  • show product entry points only when the matching product flag is true
  • verify the API key belongs to the expected tenant and application

iframe Is Blank Or Blocked

Likely causes:

  • your domain is not allowlisted for the application
  • your Content Security Policy does not allow the Hosted Experience URL as a frame source
  • browser or app shell settings block embedded content

Fix:

  • ask Aarthik Labs to allowlist your production and staging domains
  • allow the Hosted Experience URL in your own CSP
  • test the same URL in a normal browser tab to separate iframe issues from URL issues

Camera Or Microphone Does Not Work

Likely causes:

  • iframe permissions are missing
  • the host app is not served over HTTPS
  • mobile webview permissions are blocked

Fix:

1allow="camera; microphone; clipboard-read; clipboard-write"

Also confirm that the hosting page uses HTTPS and that mobile app permissions are granted.

Borrower Is Stuck On A Lender Page In Mobile App

Likely causes:

  • the mobile bridge is not registered before Hosted loads
  • the app does not handle aarthik-labs:open-external
  • the lender page was opened in the same Hosted surface instead of an app-controlled external surface
  • the external surface does not provide a clear return action

Fix:

  • register the AarthikLabs bridge before opening Hosted
  • handle the aarthik-labs:open-external event
  • open payload.external_url in an app-controlled surface
  • return to the existing Hosted surface when possible
  • use payload.resume_url if Hosted must be reopened

URL Worked Once But Fails Later

Likely cause:

  • embedURL contains a short-lived bootstrap token in the URL fragment

Fix:

  • do not reuse old URLs
  • call your back-end again and create a fresh URL for the same borrowerProviderID

Borrower Starts A New Journey Unexpectedly

Likely causes:

  • borrowerProviderID changed for the same borrower
  • your app generated a new random ID on each click
  • contact number and borrower ID mapping changed between sessions

Fix:

  • use a stable borrower ID from your own system
  • keep the same borrowerProviderID for the same borrower across sessions
  • avoid temporary session IDs, device IDs, or lead IDs that change later

What To Share With Support

When escalating an issue to Aarthik Labs, share:

  • environment: test or live
  • tenant or application name
  • approximate timestamp
  • endpoint called
  • HTTP status code
  • borrowerProviderID
  • journeyType
  • sanitized request payload
  • screenshot or screen recording if the issue is visual

Do not share the platform API key or full borrower PII in support channels.