Errors

The Helpdesk API uses standard HTTP status codes and returns structured error objects.

Error response format

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Ticket not found",
    "status": 404
  }
}

Some errors include a details field with additional context:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "status": 422,
    "details": {
      "subject": [{ "code": "REQUIRED", "message": "Subject is required" }]
    }
  }
}

Authentication and authorization errors

Code	Status	Description
INVALID_API_KEY	401	API key is missing, invalid, or revoked
MISSING_WORKSPACE	400	X-Workspace-Id header is required
INSUFFICIENT_API_PERMISSION	403	API key lacks the required permission level or workspace access

General errors

Code	Status	Description
BAD_REQUEST	400	Malformed request body or missing required wrapper object
NOT_FOUND	404	The requested resource does not exist
VALIDATION_ERROR	422	A required field is missing or invalid
CONFLICT	409	Resource conflict (e.g. duplicate value)
RATE_LIMIT_EXCEEDED	429	Too many requests — retry after the Retry-After header value

Ticket errors

Code	Status	Description
TICKET_CLOSED	403	Cannot add messages to closed tickets
CLOSED_STATUS_SYSTEM_ONLY	403	Closed status can only be set by system automations

Ticket field errors

Code	Status	Description
IMMUTABLE_FIELD	422	Cannot change type or fieldKey after creation
SYSTEM_FIELD	422	System fields cannot be modified or deleted
INVALID_FIELD_TYPE	422	Options are only available for dropdown/multiselect fields
DUPLICATE_OPTION_VALUE	409	An option with this value already exists on the field
TOO_MANY_OPTIONS	422	Maximum of 2000 options per field
OPTION_IN_USE	422	Cannot delete an option that is in use on tickets

Rate limiting

The API enforces a limit of 400 requests per minute per API key. Every response includes rate limit headers:

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Seconds to wait (only on 429 responses)