Troubleshooting

The symptoms we see most often during integrations, their probable cause, and what to do about each one.

Symptom	Probable cause	What to do
`401` when minting a session token	Key revoked, expired or malformed (bad checksum).	Verify the key in your secret store; ask us for a rotation if in doubt.
`403` — session token lacks a scope	The token was minted before a permissions change.	Re-mint the token — scopes travel inside it.
`422` when provisioning a client	A blueprint placeholder has no value, or connector credentials are empty.	The `detail` field names the exact missing key. Send it and retry — the call is idempotent.
Widget doesn’t mount / blank iframe	The page’s origin is not in your key’s allowed origins.	Register the exact origin (scheme + host + port). Localhost and staging origins count as distinct.
Meta rejects the authorization during signup	The OAuth code expired or was reused.	Close the modal and restart the flow — codes are single-use and short-lived.
`409` when connecting a number	That WhatsApp number is already linked to another workspace.	Contact us to release the number from its previous workspace first.
`413` when sending a broadcast	The audience exceeds your per-send cap (default 250).	Split the send into batches, or ask us to raise your cap.
A template doesn’t appear in the modal	It isn’t APPROVED yet in that client’s WhatsApp Business account.	Wait for Meta’s approval; the modal only offers approved templates.
`token_refresh_failed` error from the SDK	Your session endpoint failed while the modal was open.	Make sure the endpoint works without user interaction (it’s called ~every 15 minutes while a modal stays open).