Déjà client de Spur ?

Se connecter
Errors

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)

StatuscodeCauseFix
400EMBED_ORIGIN_NOT_ALLOWEDorigin isn’t on your allowed list, or isn’t a valid origin.Add it in Settings → Developers → Embeds, or fix the value you send.
400EMBED_CONTACT_REQUIREDNone of contact.number, contact.id or conversationId was sent.Send one of them.
400EMBED_CONTACT_NUMBER_INVALIDcontact.number isn’t a valid phone number, or doesn’t start with +.Send it with + and the country code, e.g. +919876543210.
400EMBED_CHANNEL_REQUIREDYour workspace has more than one WhatsApp number and the request didn’t say which.Send channelId, or mint with conversationId.
400NonechannelId 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.
401NoneThe API key is missing, wrong or deleted.Check the key on your server.
403NoneThe request wasn’t made with a workspace API key.Use an API key from Settings → Developers → API.
403EMBED_USER_NO_INBOX_ACCESSThe Spur user’s role has no access to the inbox.Give the role Inbox access.
403EMBED_CONVERSATION_NOT_ACCESSIBLEThe 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.
404EMBED_USER_NOT_FOUNDNo member of your workspace has that email or ID.Check user.email or user.id.
404EMBED_CONTACT_NOT_FOUNDNo contact with that contact.id in your workspace.Mint with contact.number to create it.
404EMBED_CONVERSATION_NOT_FOUNDNo WhatsApp conversation with that conversationId in your workspace.List the contact’s conversations and use one of those.
404EMBED_CHANNEL_NOT_FOUNDchannelId isn’t one of your WhatsApp numbers, or no number is connected.Use an ID from Settings → Developers → Embeds.
409EMBED_USER_INACTIVEThe Spur user is deactivated or hasn’t accepted their invite.Reactivate them or wait for them to accept.
429EMBED_RATE_LIMITEDMore than 600 tokens in a minute for your workspace.Wait retryAfter seconds. Switch conversations with spur:openConversation instead of minting.

Other endpoints

EndpointStatusCause
GET /contacts/{contactId}/conversations404The contact isn’t in your workspace, or isn’t a WhatsApp contact.
POST /conversations/{conversationId}/assign400to is missing or invalid, userId is missing with to: "user", or that user isn’t in your workspace.
POST /conversations/{conversationId}/assign403The request wasn’t made with a workspace API key.
POST /conversations/{conversationId}/assign404CONVERSATION_NOT_FOUND: no such conversation in your workspace.
POST /conversations/{conversationId}/assign409The user hasn’t accepted their invite.
All three401The API key is missing, wrong or deleted.

Errors in the frame

Eventreason / codeCauseWhat to do
spur:authRequiredexpiredThe 8-hour session ended, or the frame reloaded without a valid session.Mint a new token.
spur:authRequiredinvalidTokenThe 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:authRequiredoriginMismatchThe 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:authRequireduserInactiveThe Spur user was deactivated or removed.Mint for an active user.
spur:errorloadFailedThe frame couldn’t load its data, for example after a network failure.The frame shows “Couldn’t load Spur” with a retry button.
spur:errorverifierMissingYour 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.