agdevhq · mintlify · Apr 13, 2026
diff --git a/docs/api/core/define-tool.mdx b/docs/api/core/define-tool.mdx
@@ -310,7 +310,7 @@ const result4 = await generate({
 });
 ```
 
-## Type Safety
+## Type safety
 
 The tool definition is fully type-safe:
 
@@ -335,7 +335,7 @@ const handler = async (args: ToolParams) => {
 };
 ```
 
-## Best Practices
+## Best practices
 
 <Tip>
   Use descriptive tool names that clearly indicate their purpose. Follow the `snake_case` convention.
@@ -353,7 +353,7 @@ const handler = async (args: ToolParams) => {
   Always validate tool results before passing them back to the model. Handle errors gracefully.
 </Warning>
 
-## Common Patterns
+## Common patterns
 
 ### 1. Database Queries
 

diff --git a/docs/api/core/embed.mdx b/docs/api/core/embed.mdx
@@ -8,7 +8,7 @@ icon: 'vector-square'
 
 The `embed()` function generates vector embeddings for text input using embedding models. Embeddings are useful for semantic search, clustering, recommendations, and other AI tasks that require numerical representations of text.
 
-## Function Signature
+## Function signature
 
 ```typescript
 export async function embed(

diff --git a/docs/api/core/errors.mdx b/docs/api/core/errors.mdx
@@ -8,7 +8,7 @@ icon: 'triangle-exclamation'
 
 core-ai provides a hierarchy of error classes for handling different types of failures when working with language models. All errors extend from `CoreAIError` and provide structured error information.
 
-## Error Hierarchy
+## Error hierarchy
 
 ```
 CoreAIError
@@ -40,19 +40,6 @@ export class CoreAIError extends Error {
 }
 ```
 
-## ValidationError
-
-Thrown when core-ai rejects invalid caller input or local request configuration before calling a provider.
-
-```typescript
-export class ValidationError extends CoreAIError {
-    constructor(message: string, cause?: unknown, provider?: string) {
-        super(message, cause, provider);
-        this.name = 'ValidationError';
-    }
-}
-```
-
 ### Properties
 
 <ParamField path="message" type="string">
@@ -68,7 +55,7 @@ export class ValidationError extends CoreAIError {
 </ParamField>
 
 <ParamField path="name" type="string">
-  Error name, always `'CoreAIError'`.
+  Error name, always `'CoreAIError'` for the base class. Subclasses override this with their own name (e.g., `'ValidationError'`, `'ProviderError'`).
 </ParamField>
 
 ### Example
@@ -89,6 +76,19 @@ try {
 }
 ```
 
+## ValidationError
+
+Thrown when core-ai rejects invalid caller input or local request configuration before calling a provider.
+
+```typescript
+export class ValidationError extends CoreAIError {
+    constructor(message: string, cause?: unknown, provider?: string) {
+        super(message, cause, provider);
+        this.name = 'ValidationError';
+    }
+}
+```
+
 ## AbortedError
 
 Thrown when an operation is cancelled via an `AbortSignal`.
@@ -389,9 +389,9 @@ try {
 }
 ```
 
-## Error Handling Patterns
+## Error handling patterns
 
-### Comprehensive Error Handling
+### Comprehensive error handling
 
 ```typescript
 import {
@@ -449,7 +449,7 @@ try {
 }
 ```
 
-### Retry Logic with Error Handling
+### Retry logic with error handling
 
 ```typescript
 async function generateWithRetry<T>(
@@ -465,12 +465,12 @@ async function generateWithRetry<T>(
       lastError = error as Error;
 
       if (error instanceof ProviderError) {
-        // Don't retry client errors (4xx)
-        if (error.statusCode && error.statusCode >= 400 && error.statusCode < 500) {
+        // Don't retry client errors (4xx) except rate limits (429)
+        if (error.statusCode && error.statusCode >= 400 && error.statusCode < 500 && error.statusCode !== 429) {
           throw error;
         }
 
-        // Retry server errors (5xx) and rate limits
+        // Retry rate limits (429) and server errors (5xx)
         if (error.statusCode === 429 || (error.statusCode && error.statusCode >= 500)) {
           const delay = Math.pow(2, i) * 1000; // Exponential backoff
           console.log(`Retrying in ${delay}ms...`);
@@ -503,7 +503,7 @@ const result = await generateWithRetry(() =>
 );
 ```
 
-### Logging and Monitoring
+### Logging and monitoring
 
 ```typescript
 function logError(error: unknown): void {
@@ -537,7 +537,7 @@ function logError(error: unknown): void {
 }
 ```
 
-### Graceful Degradation
+### Graceful degradation
 
 ```typescript
 async function generateWithFallback(
@@ -570,7 +570,7 @@ async function generateWithFallback(
 }
 ```
 
-## Best Practices
+## Best practices
 
 <Tip>
   Always check for specific error types before general ones. Use `instanceof` checks in order from most specific to least specific.
@@ -592,7 +592,7 @@ async function generateWithFallback(
   Log error details including provider, status codes, and causes for debugging and monitoring.
 </Tip>
 
-## Common HTTP Status Codes
+## Common HTTP status codes
 
 - `400` - Bad Request (invalid parameters)
 - `401` - Unauthorized (invalid API key)

diff --git a/docs/api/core/generate-image.mdx b/docs/api/core/generate-image.mdx
@@ -228,7 +228,7 @@ console.log('Landscape:', landscape.images[0].url);
 console.log('Square:', square.images[0].url);
 ```
 
-## Model Support
+## Model support
 
 Different providers expose image generation models through `imageModel()`:
 

diff --git a/docs/concepts/error-handling.mdx b/docs/concepts/error-handling.mdx
@@ -7,7 +7,7 @@ description: CoreAIError, ProviderError, and structured output error types in co
 
 core-ai provides a hierarchy of error types that help you handle failures gracefully. For the complete API surface, see the [errors reference](/api/core/errors).
 
-## Error Hierarchy
+## Error hierarchy
 
 ```typescript
 Error
@@ -181,7 +181,7 @@ try {
 - Provider API errors
 - Timeout errors
 
-## Structured Output Errors
+## Structured output errors
 
 Errors specific to structured output generation (`generateObject` and `streamObject`).
 
@@ -313,7 +313,7 @@ try {
 - Values that don't match schema constraints
 - Invalid enum values
 
-## Complete Error Handling Example
+## Complete error handling example
 
 ```typescript
 import {
@@ -390,9 +390,9 @@ async function generateUserProfile(prompt: string) {
 }
 ```
 
-## Retry Strategies
+## Retry strategies
 
-### Exponential Backoff
+### Exponential backoff
 
 ```typescript
 async function generateWithRetry(
@@ -417,7 +417,7 @@ async function generateWithRetry(
 }
 ```
 
-### Circuit Breaker
+### Circuit breaker
 
 ```typescript
 class CircuitBreaker {
@@ -466,7 +466,7 @@ const result = await breaker.execute(() =>
 );
 ```
 
-## Validation Best Practices
+## Validation best practices
 
 <Tip>
   **Validate inputs before sending:** Check for empty messages, validate file sizes, and ensure proper content types before making API calls to avoid unnecessary errors.
@@ -488,7 +488,7 @@ function validateMessages(messages: Message[]): void {
 }
 ```
 
-## Logging Errors
+## Logging errors
 
 <Tip>
   **Log error details for debugging:** Include provider, model, status codes, and raw output when available to help diagnose issues.
@@ -534,7 +534,7 @@ try {
 }
 ```
 
-## Next Steps
+## Next steps
 
 - Learn about [Providers](/concepts/providers) for provider-specific behavior
 - Explore [Configuration](/concepts/configuration) for controlling generation