Errors and fixes
REST calls return a status code and a JSON body. Inside the frame, problems reach your page as events, and the frame itself shows a plain “Couldn’t load Spur” panel. It never shows a password form.
Error envelope
Branch on statusCode and, where present, code. message is written for people and may change.
400 Bad Request
{
"statusCode": 400,
"error": "Bad Request",
"code": "EMBED_CHANNEL_REQUIRED",
"message": "This workspace has more than one WhatsApp number. Send channelId (or conversationId) to say which one to open.",
"source": "spur"
}Token errors (POST /embed/tokens)
| Status | code | Cause | Fix |
|---|---|---|---|
| 400 | EMBED_ORIGIN_NOT_ALLOWED | origin isn’t on your allowed list, or isn’t a valid origin. | Add it in Settings → Developers → Embeds, or fix the value you send. |
| 400 | EMBED_CONTACT_REQUIRED | None of contact.number, contact.id or conversationId was sent. | Send one of them. |
| 400 | EMBED_CONTACT_NUMBER_INVALID | contact.number isn’t a valid phone number, or doesn’t start with +. | Send it with + and the country code, e.g. +919876543210. |
| 400 | EMBED_CHANNEL_REQUIRED | Your workspace has more than one WhatsApp number and the request didn’t say which. | Send channelId, or mint with conversationId. |
| 400 | None | channelId doesn’t match the conversationId you sent, or a field failed validation (message is then a list), such as a missing codeChallenge or one that isn’t 43 base64url characters. | Send conversationId alone, or fix the listed fields. |
| 401 | None | The API key is missing, wrong or deleted. | Check the key on your server. |
| 403 | None | The request wasn’t made with a workspace API key. | Use an API key from Settings → Developers → API. |
| 403 | EMBED_USER_NO_INBOX_ACCESS | The Spur user’s role has no access to the inbox. | Give the role Inbox access. |
| 403 | EMBED_CONVERSATION_NOT_ACCESSIBLE | The user’s permissions don’t cover that conversation, e.g. it’s assigned to someone else and the role can only see its own. | Let the role see other people’s conversations, or mint for the assignee. |
| 404 | EMBED_USER_NOT_FOUND | No member of your workspace has that email or ID. | Check user.email or user.id. |
| 404 | EMBED_CONTACT_NOT_FOUND | No contact with that contact.id in your workspace. | Mint with contact.number to create it. |
| 404 | EMBED_CONVERSATION_NOT_FOUND | No WhatsApp conversation with that conversationId in your workspace. | List the contact’s conversations and use one of those. |
| 404 | EMBED_CHANNEL_NOT_FOUND | channelId isn’t one of your WhatsApp numbers, or no number is connected. | Use an ID from Settings → Developers → Embeds. |
| 409 | EMBED_USER_INACTIVE | The Spur user is deactivated or hasn’t accepted their invite. | Reactivate them or wait for them to accept. |
| 429 | EMBED_RATE_LIMITED | More than 600 tokens in a minute for your workspace. | Wait retryAfter seconds. Switch conversations with spur:openConversation instead of minting. |
Other endpoints
| Endpoint | Status | Cause |
|---|---|---|
| GET /contacts/{contactId}/conversations | 404 | The contact isn’t in your workspace, or isn’t a WhatsApp contact. |
| POST /conversations/{conversationId}/assign | 400 | to is missing or invalid, userId is missing with to: "user", or that user isn’t in your workspace. |
| POST /conversations/{conversationId}/assign | 403 | The request wasn’t made with a workspace API key. |
| POST /conversations/{conversationId}/assign | 404 | CONVERSATION_NOT_FOUND: no such conversation in your workspace. |
| POST /conversations/{conversationId}/assign | 409 | The user hasn’t accepted their invite. |
| All three | 401 | The API key is missing, wrong or deleted. |
Errors in the frame
| Event | reason / code | Cause | What to do |
|---|---|---|---|
| spur:authRequired | expired | The 8-hour session ended, or the frame reloaded without a valid session. | Mint a new token. |
| spur:authRequired | invalidToken | The token was already used, expired, or never existed, or the code verifier in spur:verify doesn’t hash to its codeChallenge. | Mint a new token for every load, with a new verifier, and send that verifier. |
| spur:authRequired | originMismatch | The frame was loaded on a different site than the token’s origin, or that origin was removed from the allowed list. | Mint with the right origin, or allow it again. |
| spur:authRequired | userInactive | The Spur user was deactivated or removed. | Mint for an active user. |
| spur:error | loadFailed | The frame couldn’t load its data, for example after a network failure. | The frame shows “Couldn’t load Spur” with a retry button. |
| spur:error | verifierMissing | Your page didn’t answer spur:ready with spur:verify within 10 seconds, or the verifier wasn’t 43 to 128 base64url characters. | Answer every spur:ready from your frame. The frame’s Try again posts spur:ready again. |