Troubleshooting

​

Marketplace & submission

• Only Karzoun can set status: 'public' — keep status: 'private' in your draft
• Confirm approval email and correct ns in Marketplace search
• Partner-only apps may be restricted to specific tenants

• Validate required fields in document schema
• Ensure ns is unique, lowercase, kebab-case
• List every secret field in auth.sensitiveKeys

​

Authentication

• Redirect URI must be exactly {SAAS_API_URL}/miniapps/{ns}/oauth2
• Check browser console for postMessage errors from the OAuth window

• Verify [[accessToken]] mapping in get_token.mapping
• For OAuth, confirm refresh_token config and auto_refresh: true
• For HTTP Basic (Authorization: 'Basic [[user]]:[[pass]]'), confirm the runtime includes Basic auto-encoding — without it the raw user:pass is sent and providers reject the call
• Confirm credentials are not swapped (e.g. WooCommerce Consumer Key as username, Secret as password)
• Test the same request with curl using sandbox credentials: curl -u 'ck_…:cs_…' 'https://store.example/wp-json/wc/v3/orders?per_page=1'

​

Webhooks & triggers

• triggers[].event must match the string produced by webhook.eventExtraction exactly
• Register webhook URL with provider: {SAAS_API_URL}/miniapps/{ns}/webhooks
• Enable signature verification only after confirming secret resolution path

• Confirm secretKey resolves from credentials vs auth.config (global vs per-tenant)
• Compare raw body bytes — re-serialized JSON will not match HMAC

​

RPC sources

• Test source.rpc_* URL manually with a valid token
• Check dataPath, valueField, and labelField against live JSON
• Provide x-fallback: 'input' so users can paste IDs when RPC fails

​

E-commerce sync

• Prefer sync.webhooks.handlers over legacy webhook.ecommerce
• Handler recordType must be order or abandonedCart
• mapping.code must extract a stable external ID
• Include sample webhook payloads in your submission

​

Getting help

1. MiniApp ns and version
2. Redacted JSON definition
3. Sample webhook payload and expected event name
4. Provider sandbox account (if available)