API Errors

API Reference: Errors

All error types in Flutter AI SDK.

Error Hierarchy

AIError (sealed base class)
├── AIAuthenticationError
├── AIRateLimitError
├── AIContextLengthError
├── AIContentFilterError
├── AIInvalidRequestError
├── AIModelNotFoundError
├── AINetworkError
├── AIServerError
└── AITimeoutError

---

AIError (Base Class)

sealed class AIError extends Equatable implements Exception {
  const AIError({
    required String message,
    String? code,
    Map<String, dynamic>? details,
    StackTrace? stackTrace,
  });
}

Properties

Property	Type	Description
message	String	Human-readable error message
code	String?	Error code from provider
details	Map<String, dynamic>?	Additional error details
stackTrace	StackTrace?	Stack trace for debugging

---

AIAuthenticationError

Thrown when authentication fails (invalid/expired API key).

final class AIAuthenticationError extends AIError {
  const AIAuthenticationError({
    required super.message,
    super.code,
    super.details,
    super.stackTrace,
  });
}

Example

try {
  await ai.chat('Hello');
} on AIAuthenticationError catch (e) {
  print('Check your API key: ${e.message}');
}

---

AIRateLimitError

Thrown when rate limit is exceeded.

final class AIRateLimitError extends AIError {
  const AIRateLimitError({
    required super.message,
    super.code,
    super.details,
    super.stackTrace,
    Duration? retryAfter,
  });
  
  final Duration? retryAfter;
}

Properties

Property	Type	Description
retryAfter	Duration?	Time to wait before retrying

Example

try {
  await ai.chat('Hello');
} on AIRateLimitError catch (e) {
  print('Rate limited: ${e.message}');
  if (e.retryAfter != null) {
    await Future.delayed(e.retryAfter!);
    // Retry
  }
}

---

AIContextLengthError

Thrown when context/conversation is too long.

final class AIContextLengthError extends AIError {
  const AIContextLengthError({
    required super.message,
    super.code,
    super.details,
    super.stackTrace,
    int? maxTokens,
    int? requestedTokens,
  });
  
  final int? maxTokens;
  final int? requestedTokens;
}

Properties

Property	Type	Description
maxTokens	int?	Maximum allowed tokens
requestedTokens	int?	Tokens that were requested

Example

try {
  await ai.chat(longMessage);
} on AIContextLengthError catch (e) {
  print('Context too long');
  print('Max: ${e.maxTokens}, Requested: ${e.requestedTokens}');
  ai.clearContext(); // Clear and retry
}

---

AIContentFilterError

Thrown when content is blocked by safety filters.

final class AIContentFilterError extends AIError {
  const AIContentFilterError({
    required super.message,
    super.code,
    super.details,
    super.stackTrace,
    List<String>? categories,
  });
  
  final List<String>? categories;
}

Properties

Property	Type	Description
categories	List<String>?	Filter categories triggered

Example

try {
  await ai.chat(message);
} on AIContentFilterError catch (e) {
  print('Content filtered');
  print('Categories: ${e.categories?.join(", ")}');
}

---

AIInvalidRequestError

Thrown for malformed requests.

final class AIInvalidRequestError extends AIError {
  const AIInvalidRequestError({
    required super.message,
    super.code,
    super.details,
    super.stackTrace,
    String? parameter,
  });
  
  final String? parameter;
}

Properties

Property	Type	Description
parameter	String?	The invalid parameter

Example

try {
  await ai.chat('Hello');
} on AIInvalidRequestError catch (e) {
  print('Invalid request: ${e.message}');
  if (e.parameter != null) {
    print('Bad parameter: ${e.parameter}');
  }
}

---

AIModelNotFoundError

Thrown when the specified model doesn't exist.

final class AIModelNotFoundError extends AIError {
  const AIModelNotFoundError({
    required super.message,
    super.code,
    super.details,
    super.stackTrace,
    String? model,
  });
  
  final String? model;
}

Properties

Property	Type	Description
model	String?	The model that wasn't found

Example

try {
  await ai.chat('Hello');
} on AIModelNotFoundError catch (e) {
  print('Model not found: ${e.model}');
}

---

AINetworkError

Thrown for network-related issues.

final class AINetworkError extends AIError {
  const AINetworkError({
    required super.message,
    super.code,
    super.details,
    super.stackTrace,
    bool isTimeout = false,
    int? statusCode,
  });
  
  final bool isTimeout;
  final int? statusCode;
}

Properties

Property	Type	Description
isTimeout	bool	Whether it was a timeout
statusCode	int?	HTTP status code

Example

try {
  await ai.chat('Hello');
} on AINetworkError catch (e) {
  if (e.isTimeout) {
    print('Request timed out');
  } else {
    print('Network error: ${e.message}');
  }
}

---

AIServerError

Thrown for provider server errors.

final class AIServerError extends AIError {
  const AIServerError({
    required super.message,
    super.code,
    super.details,
    super.stackTrace,
    int? statusCode,
  });
  
  final int? statusCode;
}

Properties

Property	Type	Description
statusCode	int?	HTTP status code (500, 502, etc.)

Example

try {
  await ai.chat('Hello');
} on AIServerError catch (e) {
  print('Server error: ${e.statusCode}');
  // Wait and retry
}

---

AITimeoutError

Thrown when a request times out.

final class AITimeoutError extends AIError {
  const AITimeoutError({
    required super.message,
    super.code,
    super.details,
    super.stackTrace,
    Duration? timeout,
  });
  
  final Duration? timeout;
}

Properties

Property	Type	Description
timeout	Duration?	The timeout duration

---

Complete Error Handling

Future<String?> safeChatRequest(FlutterAI ai, String message) async {
  try {
    final response = await ai.chat(message);
    return response.text;
    
  } on AIAuthenticationError {
    // Invalid API key
    return null;
    
  } on AIRateLimitError catch (e) {
    // Rate limited - wait and retry
    if (e.retryAfter != null) {
      await Future.delayed(e.retryAfter!);
      return safeChatRequest(ai, message);
    }
    return null;
    
  } on AIContextLengthError {
    // Context too long - clear and retry
    ai.clearContext();
    return safeChatRequest(ai, message);
    
  } on AIContentFilterError {
    // Content was filtered
    return 'Your message could not be processed.';
    
  } on AIInvalidRequestError catch (e) {
    // Bad request
    print('Invalid: ${e.parameter}');
    return null;
    
  } on AIModelNotFoundError catch (e) {
    // Model doesn't exist
    print('Model not found: ${e.model}');
    return null;
    
  } on AINetworkError catch (e) {
    // Network issues
    if (e.isTimeout) {
      return 'Request timed out';
    }
    return 'Network error';
    
  } on AIServerError {
    // Provider issues
    return 'Service temporarily unavailable';
    
  } on AIError catch (e) {
    // Other AI errors
    print('AI Error: ${e.message}');
    return null;
    
  } catch (e) {
    // Unexpected errors
    print('Unexpected: $e');
    return null;
  }
}

---

Related

• Error Handling - Error handling guide
• API-FlutterAI - Main class reference