Troubleshooting
First identify which flow failed: the runtime iframe bridge, setup/configuration, your backend's installed-extension request, a user-wide program, or OAuth account linking. Their message types and credentials differ. Start with Developer API Overview if you are unsure which flow applies.
No Response From Parent
Open the extension from its installed entry in a Chastify lock. Opening your hosted page directly does not supply the parent bridge or a valid launch context.
Check these in order:
- Decode the current URL fragment and confirm it contains
bridge.v: 1,bridge.nonce, andbridge.parentOrigin. Do not overwrite that fragment with your own hash router. - Register the response listener before sending. Runtime requests use
chastify:ext:req,v: 1, a unique stringid, the current nonce, and a supported action. - Send to the exact
bridge.parentOrigin. The app's Allowed origins must include the hosted iframe's origin, including its scheme and port. They are the two different sides of the message exchange. - Confirm the iframe finished loading. The parent registers the runtime bridge on iframe load; an immediate startup request can arrive too early. Try a user-triggered
session.getafter load to isolate this. - Accept only a response from
window.parent, the expected origin,type: 'chastify:ext:resp', version 1, and your pending request ID. Ordinary runtime responses do not echo the nonce.
The sample helper times out after 15 seconds with bridge_timeout. A timeout alone does not identify whether loading, an origin mismatch, a missing listener, or the underlying request caused the failure. An error response such as unknown_action means the parent received the request; it is a different problem from receiving nothing.
The seven supported runtime actions are session.get, state.get, metadata.get, regularActions.get, files.capabilities, files.list, and files.get. Writes, device commands, and runtime uploads require your backend. See the working examples.
For a blank iframe, also inspect its document request and browser console. Your host must serve the page successfully and permit Chastify to embed it; a browser embedding error cannot be repaired by changing the bridge nonce.
Backend Credentials and Role Errors
Installed-extension requests use both an app-scoped Developer key and the current x-chastify-main-token. The URL uses the installed extension's sessionId, not its app ID or lock ID.
| Error | What to check |
|---|---|
app_scoped_key_required | A user-wide key belongs with /api/apps/v1/*, not installed-extension session routes. |
main_token_required | Forward the current launch token to your backend and include its header. The nonce is not this token. |
invalid_main_token, revoked_main_token, expired_main_token | Obtain a new launch context by reopening the extension and update the backend's launch context. |
session_mismatch, lock_mismatch, extension_mismatch | The key, launch token, route session, and installed app must refer to the same context. |
grant_role_mismatch | The launch user's wearer/keyholder role changed. Reopen from the account that currently has the required role. |
server_credentials_required | The mutation needs backend authentication; sending it through the browser bridge will not supply that. |
insufficient_scope | Check both the key's permissions and the installed extension's effective scopes. |
forbidden or an action-specific role/trust error | The current caller or lock settings do not authorize that operation. A backend key does not elevate a wearer to keyholder. |
Launch tokens currently expire after ten hours. Issuing another token for the same user and installed extension revokes earlier grants, so opening a second tab can invalidate the first tab's backend token. Do not poll the /auth endpoint to refresh ordinary session data.
Keep Developer keys on your server. For other credential types, use External API & Programs or OAuth Account Linking.
403 extension_not_enabled
The installed extension is disabled for this lock. Open its configuration and enable/save it through the authorized Chastify UI, then reopen it. Availability in the extension catalogue does not mean it is enabled on this lock.
A 404 extension_not_found can instead mean the underlying app is unavailable or inactive. For an unreleased app, check developer/tester access using Extension Release & Beta Testing.
409 lock_ended
The lock session is no longer eligible for extension operations. Stop its background reads and writes and return to Chastify to check the session. Repeating the request or changing the token does not reactivate an ended session.
Do not substitute a different active lock automatically when an operation fails. Start a new launch deliberately and keep its identifiers separate from the previous session.
429 Rate Limit
The installed-extension defaults are 300 reads, 120 writes, 10 uploads, 30 actions, and 30 token requests per minute. App overrides and other route families can differ. Endpoints share their applicable bucket; setup requests by one user can also share capacity across apps.
For direct HTTP requests, inspect Retry-After or JSON retryAfter and wait before a bounded retry. X-RateLimit-Reset is an ISO timestamp. See Rate Limits for counting rules and endpoint mapping.
The runtime bridge reports error.code: 'rate_limit_exceeded' but currently does not forward HTTP status or the retry delay. Pause reads for a minute and offer a retry. Checking only error.status === 429 in the iframe will miss this response.
An explicit rate-limit rejection and a lost response are different outcomes. A timeout or server error after submitting an action may leave its result uncertain. Check state, history, or delivery status before repeating time changes, tasks, progress, or device commands.
Device Command Fails
For an installed extension, read session.get and its deviceControl.supportedCommands before offering a control. Recheck when the device or lock settings change. The user-wide session response has a different shape; do not expect the iframe capability object there.
Send the command through your backend with the required credentials. bridge.request('device.command', ...) is unsupported.
Check the returned error against:
- The wearer's configured device, its capabilities, and available delivery route.
- Current wearer/keyholder permissions, consent, and lock/device policy.
- The command's parameters and model-specific support, especially timed random/berserk modes.
- Queue, connection, or acknowledgement status.
An accepted request may be queued; active flags are not a physical delivery receipt. A stop result is also not proof that every device has stopped or that all outstanding mandatory deliveries were cancelled. Follow Shock Delivery & Queues and the device command examples.
Setup Page Not Saving Config
Setup uses a separate protocol from the runtime bridge. Use the setup launch's nonce and parent origin, and validate message source, origin, and version.
- Register listeners, then send
chastify:ext:setup:readywithv: 1and the current nonce. - Handle
chastify:ext:setup:init, which contains existingconfigandcontext. Initialize your form without dropping fields it does not own. - Send
chastify:ext:setup:configwith the current full configuration when it changes. - Answer
chastify:ext:setup:get_configpromptly with anotherchastify:ext:setup:config. The parent waits about 1.5 seconds before using its last draft, so do not start an upload or other slow work at this point. - Save through the parent Chastify UI. Sending a configuration message updates its draft; it does not persist the lock or template by itself.
Inspect validation or eligibility errors shown after Save. Keep the draft available so the user can correct it. A setup upload response alone does not mean its reference was claimed in saved configuration.
See Setup protocol and the sample apps/extension/src/pages/SetupPage.tsx.
Uploaded Image Is Missing
Store a stable file ID, then request a fresh signed URL for display. Signed URLs normally expire after ten minutes. A browser blob: URL only refers to the local preview, and an extension-file:ID reference is not itself an image URL.
For setup images, save the structured chastify_storage reference and actual configuration before the draft expires after 24 hours. Check the setup/runtime ownership limitations in Extension File Storage: a successfully claimed setup file is not automatically readable through every runtime file route.
files.capabilities.enabled reports whether uploads are available. It does not itself forbid reading existing files. For file_not_found, check the app/user/session/lock context rather than removing ownership checks or substituting another file ID.
Webhook Is Missing or Repeated
Check the app's webhook setting, saved endpoint, receiver response, and current token configuration. A successful test request checks that path at that moment; it does not prove every future event will arrive.
Events can be retried, delayed, or dropped after delivery failure. The current payload ID is regenerated on retries, so it is not a stable deduplication key for one source event. See Webhooks for supported events and delivery limitations before triggering side effects from a callback.
What to Include in a Developer Report
Include the affected flow, endpoint/action, approximate time, reproduction steps, HTTP status or bridge error code, and a sanitized response. State whether the failure happens in setup, after installation, or only after reopening/changing the session.
Remove Developer keys, launch/access tokens, webhook authentication values, signed image URLs, private configuration, and personal content. Never share a full iframe launch URL. Use Contacting Support for the appropriate channel.