Troubleshooting: developers
Fixes for API key errors, webhook failures and signatures, duplicate deliveries, mini app problems, AI tool connections and live chat integration.
- Who can use this
- Developer
Fixes for API key errors, webhook failures and signatures, duplicate deliveries, mini app problems, AI tool connections and live chat integration.
Start here when an integration misbehaves. Each table gives the error or symptom, why it happens and what to do. The linked pages explain each feature in full.
| What you see | Why | What to do |
|---|---|---|
| No Developers under Settings → App | Webhooks are not in your plan, or you lack Manage Webhooks. There is no switch for webhooks in Settings | Check Billing → Current Plan, or ask a Manager for the permission. See Set up webhooks |
| "Access Restricted" on a webhook page | You lack Manage Webhooks | Ask your administrator |
| No Developer portal or API Tokens | You lack Manage Settings, or your panel has no developer portal | Ask a Manager |
| Health → Errors or Insights says "Coming soon" | Not available yet | Use Deliveries filtered by Failed |
| What you see | Why | What to do |
|---|---|---|
401 unauthenticated | Key missing, revoked, expired, mistyped, or called from outside its IP allowlist. An API token from Settings → Integration → API Tokens is also refused: the REST API takes developer keys only | Check the key's status and your server's outbound IP. See API tokens and developer keys |
403 insufficient_scope | The key lacks the permission for this call | Create a key with that scope |
428 confirm_required | An irreversible call sent without Api-Confirm | Add Api-Confirm: <verb>. See REST API basics |
409 conflict | The first request with this Idempotency-Key is still running | Wait, then retry |
429 rate_limited | Over a rate limit | Wait the Retry-After seconds |
| Calls "work" but nothing changes | You are using a test key | Use a live key |
| "Set up two-step sign-in first" | A broadcast key needs 2FA on your profile | Turn on two-factor authentication |
| What you see | Why | What to do |
|---|---|---|
| Your server rejects every signature | The body was parsed before hashing, or the whsec_ prefix was dropped | Hash the raw bytes with the full secret. See Webhook deliveries, retries and signatures |
| Signatures fail after rotating the secret | Your server has only the old secret and the 24-hour overlap ended | Deploy the new secret |
| Timestamp check fails | Your server's clock is wrong | Sync the clock |
| Endpoint shows Disabled (auto) | 15 failures in a row | Fix the server, turn the endpoint on, then replay missed events from Events |
Delivery failed with blocked_destination | The URL points to a private or internal address | Use a public HTTPS address |
| The same event arrives twice | A retry or replay | Deduplicate on Webhook-Id, never on Wc-Webhook-Id |
| "URL must use HTTPS" | The address starts with http:// | Use HTTPS. See Set up webhooks |
| "No active endpoints. Create one first, then send a test event." | Every endpoint is off or none exist | Create or enable one |
| What you see | Why | What to do |
|---|---|---|
| Blank tab; the console shows a frame-ancestors error | Your server forbids being framed | Allow the panel's address in frame-ancestors. See Build a mini app |
| The app loads but does nothing | ready() was never called | Call ready() at startup |
An action returns missing_scope | That permission was not ticked when the app was added | Tick it under What this app is allowed to do |
| Background access card says "Not approved yet" | Nobody approved background access for this install | Click Approve and save. See Mini app server access |
invalid_install_code | The code expired, was used, or was replaced | Use the code from the latest hook delivery. See Mini app server access |
401 token_revoked | Access was turned off, reset or the app was uninstalled | A Manager reconnects it; do not loop retries |
| What you see | Why | What to do |
|---|---|---|
entitlement_required | MCP access, or that tool's feature, is not in your plan | Ask the assistant to run whoami; check Billing. See MCP server |
insufficient_scope from an AI assistant | You did not grant that permission on the consent screen | Reconnect and tick it |
| Sign-in to connect an assistant loops or fails | Wrong server address, or you lack Connect AI tools | Check the address; ask a Manager for the permission |
| Agent API requests refused as unauthorised | Wrong internal key or company id | See Connect your backend to an AI agent |
| What you see | Why | What to do |
|---|---|---|
| The chat does not appear on your site | The site's address is not in Your websites, or the code is missing on that page | Add the exact address and check the code |
| A page action does nothing | No onAction handler for that name, or its category is off | See Live chat JavaScript API and web SDK |
Do it with Copilot
Do it with Copilot
(turning it on needs approval)
Do it with Copilot