Error Handling

HTTP Status Codes

Code	Description
200	OK - Request succeeded
400	Bad Request - Missing parameter or invalid request structure
401	Unauthorized - Invalid or missing API key
403	Forbidden - API key owner lacks permission for this action
404	Not Found - Resource doesn't exist
422	Unprocessable Entity - Semantic errors in parameters
429	Too Many Requests - Rate limit exceeded (see Rate Limiting)
500	Internal Error - Server-side issue (rare)

Error Types

All errors follow a consistent structure with a type field indicating the error category:

Error Type	Description
BaseError	Base schema for all error types
RecordError	Error when saving a record
InvalidParameterError	One or more parameters are missing or invalid
AuthError	Authentication failed (missing or expired token)
MaintenanceError	Holistics is in maintenance mode
SubscriptionError	Subscription lacks permission for this resource
PermissionDeniedError	API key owner lacks access to this resource
InternalHolisticsError	Internal error - provide debug id to support
InvalidOperationError	Action blocked by system constraints

Error Response Format

All error responses follow this structure:

{
  "error": {
    "type": "InvalidParameterError",
    "message": "Parameter 'source_id' is required",
    "debug_id": "abc123xyz"
  }
}

Handling Errors

Best practices:

1. Check status codes first - Use HTTP status to determine error category
2. Parse error type - Use the type field for specific error handling
3. Log debug IDs - For InternalHolisticsError, save the debug_id for support requests
4. Validate inputs - Prevent InvalidParameterError by validating before sending

Example error handling (Python):

import requests

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    return response.json()
elif response.status_code == 401:
    raise Exception("Invalid API key")
elif response.status_code == 403:
    raise Exception("Permission denied")
elif response.status_code == 422:
    error = response.json().get('error', {})
    raise Exception(f"Validation error: {error.get('message')}")
elif response.status_code == 429:
    # Handle rate limiting
    pass
else:
    error = response.json().get('error', {})
    raise Exception(f"API error: {error.get('message')} (debug_id: {error.get('debug_id')})")