Error Handling

All API errors return a consistent JSON structure with a machine-readable code and human-readable message.

Error format

{
  "error": {
    "code": "auth.unauthorized",
    "message": "Invalid or missing API key"
  }
}

Error codes

Status	Code	Meaning
401	`auth.unauthorized`	Missing or invalid API key
403	`auth.forbidden`	Key valid but insufficient permissions
404	`not_found`	Resource does not exist
409	`conflict`	Duplicate or conflicting resource
422	`validation.failed`	Request body failed schema validation
429	`rate_limit.exceeded`	Too many requests
500	`internal`	Server error

SDK error handling

import { HelmdeskError } from '@helmdesk/sdk'

try {
  await client.tickets.get('invalid-id')
} catch (err) {
  if (err instanceof HelmdeskError) {
    console.log(err.status) // 404
    console.log(err.code)   // "not_found"
    console.log(err.message) // "Ticket not found"
  }
}

Validation errors

When a 422 error occurs, the response includes a details object with field-level errors:

{
  "error": {
    "code": "validation.failed",
    "message": "Validation failed",
    "details": {
      "subject": "Required",
      "customerEmail": "Invalid email address"
    }
  }
}