Error Codes

Troubleshooting reference for Blendlix Call Service public error codes.

Error Codes

Use this page to understand what an error means, why it happens, and how to resolve it.

REST token errors

Code	Meaning	Why it happens	How to resolve
`INVALID_REQUEST_BODY`	The JSON body is missing or invalid.	Invalid JSON, unknown fields, or multiple JSON payloads.	Send valid JSON that matches the endpoint schema.
`PRODUCT_REQUIRED`	Product is missing.	Product auth did not infer a product and the request did not include one.	Include `product` or use credentials mapped to one product.
`CONTEXT_TYPE_REQUIRED`	`context_type` is missing.	The request did not include a context type.	Send a non-empty context type.
`CONTEXT_ID_REQUIRED`	`context_id` is missing.	The request did not include a context ID.	Send a non-empty context ID.
`ROLE_REQUIRED`	Caller role is missing.	The request did not include `role`.	Send a non-empty role.
`USER_ID_REQUIRED`	User ID is missing.	The request did not include `user_id`.	Send the authenticated application user ID.
`DISPLAY_NAME_REQUIRED`	Display name is missing.	The request did not include `display_name`.	Send a user-friendly display name.
`ALLOWED_PEER_ROLE_REQUIRED`	Allowed receiver role is missing.	The request did not include `allowed_peer_role`.	Send the role this token may invite.
`TOKEN_ISSUE_FAILED`	Token could not be created.	Service-side signing failure.	Retry later and contact support if it continues.

Product authentication errors

Code	Meaning	Why it happens	How to resolve
`PRODUCT_AUTH_KEY_ID_REQUIRED`	Product key ID is missing.	Header is not present.	Send `X-BCS-Product-Key-ID`.
`PRODUCT_AUTH_SECRET_REQUIRED`	Product secret is missing.	Header is not present.	Send `X-BCS-Product-Secret`.
`PRODUCT_AUTH_INVALID_KEY`	Product key is unknown or disabled.	Wrong key ID or disabled product.	Verify the key ID with Blendlix.
`PRODUCT_AUTH_INVALID_SECRET`	Product secret is wrong.	Secret does not match the registered product.	Rotate or correct the secret.
`PRODUCT_AUTH_PRODUCT_MISMATCH`	Product name does not match the key.	Request body product differs from the authenticated product.	Use the correct product value or omit it when credentials map to one product.
`PRODUCT_AUTH_FAILED`	Product authentication failed unexpectedly.	Internal validation failed.	Retry and contact support if it continues.

Rate limit errors

Code	Meaning	Why it happens	How to resolve
`BOOTSTRAP_IP_RATE_LIMITED`	Too many token requests from one IP.	The same IP requested too many session tokens.	Slow down requests and retry after the `Retry-After` value.
`BOOTSTRAP_KEY_RATE_LIMITED`	Too many token requests for one product key.	A product backend is requesting too many tokens.	Check for loops, retries, or duplicate client requests.
`BOOTSTRAP_RATE_LIMIT_ERROR`	Rate limit check failed.	Service could not verify rate limit state.	Retry later.
`INVITE_RATE_LIMITED`	Too many call invites.	A participant sent too many invites in a short period.	Add client-side debounce and wait before retrying.
`INVITE_RATE_LIMIT_ERROR`	Invite rate limit check failed.	Service could not verify invite rate state.	Retry later.

WebSocket and call errors

Code	Meaning	Why it happens	How to resolve
`INVALID_PAYLOAD`	WebSocket payload is invalid.	Message is not valid JSON or not a valid envelope.	Send a valid event envelope.
`INVALID_INVITE_PAYLOAD`	Invite payload is missing required fields.	`callee_user_id`, `callee_role`, `context_type`, or `context_id` is missing.	Send all required invite fields.
`CALL_PEER_ROLE_NOT_ALLOWED`	Token cannot invite that receiver role.	`callee_role` is not in token `allowed_peer_roles`.	Request a new token with the correct allowed peer role after backend authorization.
`CALL_ALREADY_ACTIVE`	The participant already has an active call.	One-active-call-per-user rule blocked a new call.	End the current call before starting another.
`CALL_UUID_REQUIRED`	`call_uuid` is missing.	Event requires a call UUID.	Include `call_uuid` from the invite response or incoming ringing event.
`CALL_NOT_FOUND`	Call does not exist or is no longer available.	Wrong UUID, expired call, or already cleaned up.	Refresh call state and retry only if a valid call exists.
`CALL_ACCEPT_FORBIDDEN`	Actor cannot accept this call.	Only the receiver can accept.	Make sure the receiver sends `call.accept`.
`CALL_REJECT_FORBIDDEN`	Actor cannot reject this call.	Only the receiver can reject.	Make sure the receiver sends `call.reject`.
`CALL_CANCEL_FORBIDDEN`	Actor cannot cancel this call.	Only the caller can cancel before answer.	Use `call.end` for accepted calls.
`CALL_END_FORBIDDEN`	Actor cannot end this call.	User is not a participant.	Use the token for one of the call participants.
`CALL_CONNECTED_FORBIDDEN`	Actor cannot mark this call connected.	User is not a participant.	Use the token for one of the call participants.
`CALL_INVALID_STATE`	Event does not match the current call state.	Example: accepting an ended call or answering before offer.	Follow the call state machine.
`CALL_ALREADY_CLOSED`	Call is already in a terminal state.	The call was ended, canceled, rejected, or missed.	Stop sending events for that call.
`CALL_PERMISSION_DENIED`	Token does not allow the requested action.	Token permissions do not include the event action.	Request a token with the correct permissions.
`CALL_PRODUCT_MISMATCH`	Token product does not match the call.	Participant token belongs to a different product.	Use tokens issued for the same product.
`CALL_PARTICIPANT_REQUIRED`	Actor is not a call participant.	User is not caller or receiver for the call.	Use the correct participant token.
`CALL_ERROR`	Generic call error.	Unexpected call handling error.	Check logs and retry safely.

History errors

Code	Meaning	Why it happens	How to resolve
`AUTH_TOKEN_REQUIRED`	Bearer token is missing.	Request did not include `Authorization`.	Send `Authorization: Bearer <session_token>`.
`AUTH_TOKEN_INVALID`	Bearer token is invalid.	Token expired, malformed, or signed incorrectly.	Request a new session token.
`CALL_HISTORY_FAILED`	History could not be loaded.	Database or service error.	Retry later.

WebSocket /v1/ws JavaScript