Error Handling

All API errors follow a standardized response format with a success: false flag and detailed error information.

Error Response Format

{
  "success": false,
  "error": {
    "code": "device_not_found",
    "detail": "You are not allowed to access the specified device. Or the specified device does not exist."
  },
  "timestamp": "2025-01-01T12:00:00.000Z"
}

Error Codes

Authentication & Authorization Errors

`authentication_error`

Status Code: 401
Meaning: Invalid or missing API key, or malformed Authorization header
Example Detail: "Invalid Authorization header. Bearer authorization is required."

Common Causes:

Missing X-Qube-API-Key header
Invalid API key format
Expired or revoked API key

Resolution:

Verify your API key is correct
Ensure proper header format: X-Qube-API-Key: your-api-key

Status Code: 400
Meaning: Device doesn't exist or you don't have access to it
Example Detail: "You are not allowed to access the specified device. Or the specified device does not exist."

Common Causes:

Invalid device ID
Device belongs to different user/account
Device has been removed or deactivated

Resolution:

Verify device ID is correct
Check device belongs to your account
Use GET /spaces/ to list accessible devices

`device_not_in_space`

Status Code: 417
Meaning: Device exists but is not associated with any space
Example Detail: "Device is not associated with any space"

Common Causes:

Device setup incomplete
Device removed from space but still exists

Resolution:

Contact support to associate device with a space
Verify device setup is complete

Space Access Errors

`not_your_space`

Status Code: 400
Meaning: The specified space doesn't belong to your account
Example Detail: "The space does not belong to you."

Common Causes:

Invalid space ID
Attempting to access another user's space
Space permissions changed

Resolution:

Use GET /spaces/ to list your accessible spaces
Verify space ID is correct

Validation Errors

`validation_error`

Status Code: 422
Meaning: Request body validation failed
Example Detail:

[
  {
    "loc": ["ssid"],
    "msg": "ensure this value has at most 32 characters"
  }
]

Common Causes:

Missing required fields
Invalid data types
Values exceeding length limits
Invalid enum values

Resolution:

Check API documentation for required fields
Verify data types match schema
Ensure string lengths are within limits

Device Operation Errors

Network/Connectivity Issues

Status Code: 400
Meaning: Device is offline or network operation failed
Example Detail: "Network details not found. Device might not be online."

Common Causes: