Server Error Handling

The Aerostack Server SDK throws structured errors to help you debug quickly and recover gracefully.

Error Types

All errors extend ServerError.

Error Class	Code Examples	Description
`DatabaseError`	`DB_TABLE_NOT_FOUND`, `DB_CONNECTION_FAILED`	Issues with D1 or Postgres queries.
`CacheError`	`CACHE_NOT_CONFIGURED`, `CACHE_GET_FAILED`	Problems accessing KV store.
`QueueError`	`QUEUE_ENQUEUE_FAILED`	Failures sending background jobs.
`StorageError`	`STORAGE_UPLOAD_FAILED`	R2 upload/download errors.
`AIError`	`AI_REQUEST_FAILED`	Cloudflare AI model errors.
`ServiceError`	`SERVICE_NOT_FOUND`	Issues invoking other services.

Handling Errors

Each error includes details with a helpful suggestion and sometimes a recoveryAction.

import { DatabaseError } from '@aerostack/sdk';
 
try {
  await sdk.db.query('SELECT * FROM users');
} catch (error) {
  if (error instanceof DatabaseError) {
    console.error(`DB Error (${error.code}):`, error.message);
    
    // Check for specific suggestions
    if (error.details?.suggestion) {
      console.log('Fix:', error.details.suggestion);
      // e.g., "Run migrations first: aerostack db migrate apply"
    }
  } else {
    // Other errors
    console.error('Unknown error:', error);
  }
}

Always wrap SDK calls in try/catch blocks, especially for network-bound operations like Database, AI, and Services.

Services Client Errors