YS Desk errors use a standard application error envelope. Stable application-level errorCode values provide machine-readable context for domain-specific failures.
Generic HTTP errors remain distinct from stable application error codes.
Error Handling Architecture
The standard error response structure is:
{
“success”: false,
“statusCode”: 400,
“timestamp”: “<ISO_8601_TIMESTAMP>”,
“path”: “<REQUEST_PATH>”,
“message”: “<ERROR_MESSAGE>”,
“error”: “<ERROR_NAME>”,
“errorCode”: “<APPLICATION_ERROR_CODE>”
}
errorCode is present when the application defines a stable domain-specific error code for the failure.
Standard Error Response Fields
| Field | Type | Description |
| success | boolean | Indicates whether the operation succeeded. Error responses use false. |
| statusCode | number | HTTP status associated with the failure. |
| timestamp | string | Error generation timestamp. |
| path | string | Request path associated with the error. |
| message | string | Human-readable error message. |
| error | string | Error category or exception name. |
| errorCode | string | Optional stable YS Desk application error code. |
Application Error Codes
INVALID_VISITOR_SESSION
HTTP status: 401
The Visitor Session token is invalid, expired, or otherwise fails validation.
Typical causes include an expired session, invalid token signature, or incorrect session context.
Recommended action: establish a fresh valid Visitor Session using the supported Web Chat authentication flow.
CHANNEL_NOT_FOUND
HTTP status: 404 or 400
The requested Channel does not exist or is unavailable.
Typical causes include an invalid <CHANNEL_TOKEN> or an unavailable Channel.
Recommended action: verify the Channel configuration and token.
DOMAIN_NOT_ALLOWED
HTTP status: 403
The current website origin is not authorized for the Channel.
Recommended action: add the required website domain to the Channel’s allowed origins configuration.
SUBSCRIPTION_SUSPENDED
HTTP status: 402
The Workspace subscription is suspended after billing enforcement.
Recommended action: resolve the billing issue and restore eligible subscription access.
CONVERSATION_LIMIT_REACHED
HTTP status: 402
The Workspace has exhausted its monthly Conversation allowance.
Recommended action: wait for the next usage period or upgrade the subscription according to the applicable plan limits.
SEAT_LIMIT_REACHED
HTTP status: 402
The Workspace has reached its available Team Member seat capacity.
Recommended action: upgrade the plan or add eligible additional seats.
LIMIT_EXCEEDED
HTTP status: 402
A configurable resource limit has been exceeded.
Examples include Saved Reply limits on lower plans.
Recommended action: remove unused resources or upgrade the subscription.
FEATURE_NOT_AVAILABLE
HTTP status: 403
The requested feature is not available on the current subscription plan.
Recommended action: upgrade to the minimum plan that includes the feature.
ACCOUNT_INACTIVE
HTTP status: 403
The User account is inactive or blocked.
Recommended action: contact the Workspace administrator.
WORKSPACE_PENDING_DELETION
HTTP status: 403
The Workspace is in its recoverable deletion period.
Recommended action: restore the Workspace within the supported recovery period.
INVITATION_REVOKED_DUE_TO_PLAN_CHANGE
HTTP status: 400
An invitation was revoked because a Workspace plan change reduced the available seat capacity before the invitation was accepted.
Recommended action: ensure sufficient seat capacity and create a new invitation.
The application error catalog and HTTP mappings are implementation-verified in the Reference audit.
Generic HTTP Status Codes
| Status | Meaning | Typical Usage |
| 400 | Bad Request | Invalid payload, validation failure, or malformed request. |
| 401 | Unauthorized | Missing, invalid, or expired authentication. |
| 402 | Payment Required | Billing, quota, or subscription enforcement. |
| 403 | Forbidden | Authentication succeeded but the requested action is not permitted. |
| 404 | Not Found | Requested resource does not exist. |
| 409 | Conflict | Duplicate or conflicting resource state. |
| 500 | Internal Server Error | Unexpected server-side failure. |
| 502 | Bad Gateway | Upstream integration or gateway failure. |
| 503 | Service Unavailable | Temporary service unavailability. |
Client Remediation Guidelines
For API clients:
- Use statusCode to determine the HTTP-level failure class.
- Use errorCode when present for domain-specific handling.
- Do not rely exclusively on the human-readable message.
- Retry only when the error is transient and the operation is safe to retry.
- Do not blindly retry authentication, permission, quota, or validation errors.
- Preserve request context such as the affected Workspace, Channel, and Conversation where appropriate.
For Web Chat clients, authentication and Channel configuration errors should be handled separately from transient transport failures.
Need Help?
Email: support@ysdesk.com
Documentation: https://docs.ysplugins.com/ys-desk