{"templateId":"GuidePage","sharedDataIds":{"sidebar":"sidebar-miniapps/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Troubleshooting","description":"Developer API, partner integration, MCP, SDK, and customer help center.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"troubleshooting","__idx":0},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Issues you may hit ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["while building"]}," a MiniApp definition before or during Karzoun review."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"marketplace--submission","__idx":1},"children":["Marketplace & submission"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["MiniApp not visible after approval"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Only Karzoun can set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: 'public'"]}," — keep ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: 'private'"]}," in your draft"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm approval email and correct ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ns"]}," in Marketplace search"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Partner-only apps may be restricted to specific tenants"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Submission rejected for schema errors"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Validate required fields in ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/miniapps/reference/document-schema"},"children":["document schema"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensure ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ns"]}," is unique, lowercase, kebab-case"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["List every secret field in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auth.sensitiveKeys"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication","__idx":2},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OAuth popup does not close"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Redirect URI must be exactly ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{SAAS_API_URL}/miniapps/{ns}/oauth2"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check browser console for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postMessage"]}," errors from the OAuth window"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Actions return 401"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[[accessToken]]"]}," mapping in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["get_token.mapping"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For OAuth, confirm ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refresh_token"]}," config and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auto_refresh: true"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test the same request with curl using sandbox credentials"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhooks--triggers","__idx":3},"children":["Webhooks & triggers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Automations never fire"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["triggers[].event"]}," must match the string produced by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook.eventExtraction"]}," exactly"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Register webhook URL with provider: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{SAAS_API_URL}/miniapps/{ns}/webhooks"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enable signature verification only after confirming secret resolution path"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Signature verification fails"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secretKey"]}," resolves from credentials vs ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auth.config"]}," (global vs per-tenant)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Compare raw body bytes — re-serialized JSON will not match HMAC"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rpc-sources","__idx":4},"children":["RPC sources"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Dropdowns empty"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source.rpc_*"]}," URL manually with a valid token"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dataPath"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["valueField"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["labelField"]}," against live JSON"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Provide ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-fallback: 'input'"]}," so users can paste IDs when RPC fails"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"e-commerce-sync","__idx":5},"children":["E-commerce sync"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Orders not appearing"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Prefer ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sync.webhooks.handlers"]}," over legacy ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook.ecommerce"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Handler ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recordType"]}," must be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["abandonedCart"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mapping.code"]}," must extract a stable external ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include sample webhook payloads in your ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/miniapps/guides/submission"},"children":["submission"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"getting-help","__idx":6},"children":["Getting help"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Include in support requests:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["MiniApp ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ns"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Redacted JSON definition"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sample webhook payload and expected event name"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Provider sandbox account (if available)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Contact: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["developers@karzoun.chat"]}," or your Karzoun partner manager."]}]},"headings":[{"value":"Troubleshooting","id":"troubleshooting","depth":1},{"value":"Marketplace & submission","id":"marketplace--submission","depth":2},{"value":"Authentication","id":"authentication","depth":2},{"value":"Webhooks & triggers","id":"webhooks--triggers","depth":2},{"value":"RPC sources","id":"rpc-sources","depth":2},{"value":"E-commerce sync","id":"e-commerce-sync","depth":2},{"value":"Getting help","id":"getting-help","depth":2}],"frontmatter":{"title":"Troubleshooting","titleTranslationKey":"sidebar.miniapps.troubleshooting","audience":"developer","status":"published","locales":["en"],"template":"GuidePage","seo":{"title":"Troubleshooting"}},"lastModified":"2026-06-23T12:06:12.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/miniapps/guides/troubleshooting","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}