fastgpt-python-sdk/docs/api/exceptions.md

# Exceptions

The SDK provides specific exceptions for different error types. All exceptions inherit from the base `FastGPTError`.

## Exception Hierarchy

```
FastGPTError
├── APIError
├── AuthenticationError
├── RateLimitError
├── ValidationError
└── StreamParseError
```

## Exception Types

### FastGPTError

Base exception class for all FastGPT SDK errors.

```python
from fastgpt_client.exceptions import FastGPTError

try:
    # SDK operation
    pass
except FastGPTError as e:
    print(f"FastGPT error: {e}")
```

---

### APIError

General API error for 4xx and 5xx responses that don't have a specific exception type.

```python
from fastgpt_client.exceptions import APIError

try:
    response = client.create_chat_completion(...)
except APIError as e:
    print(f"API error: {e.message}")
    print(f"Status code: {e.status_code}")
    print(f"Response data: {e.response_data}")
```

**Attributes:**

| Attribute | Type | Description |
|-----------|------|-------------|
| `message` | `str` | Error message |
| `status_code` | `int` | HTTP status code |
| `response_data` | `dict | None` | Full error response data |

---

### AuthenticationError

Raised when authentication fails (401 status code).

```python
from fastgpt_client.exceptions import AuthenticationError

try:
    response = client.create_chat_completion(...)
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
    print("Please check your API key")
```

**Common Causes:**

- Invalid API key
- Missing API key
- Expired API key
- API key format incorrect

---

### RateLimitError

Raised when rate limit is exceeded (429 status code).

```python
from fastgpt_client.exceptions import RateLimitError

try:
    response = client.create_chat_completion(...)
except RateLimitError as e:
    print(f"Rate limit exceeded: {e.message}")
    if e.retry_after:
        print(f"Retry after {e.retry_after} seconds")
```

**Attributes:**

| Attribute | Type | Description |
|-----------|------|-------------|
| `message` | `str` | Error message |
| `retry_after` | `str | None` | Suggested retry delay (from `Retry-After` header) |
| `status_code` | `int` | HTTP status code (429) |
| `response_data` | `dict | None` | Full error response data |

---

### ValidationError

Raised when request validation fails (422 status code).

```python
from fastgpt_client.exceptions import ValidationError

try:
    response = client.create_chat_completion(
        messages=[{"role": "user", "content": "Hello"}],
        invalid_param="value"
    )
except ValidationError as e:
    print(f"Validation error: {e.message}")
    print(f"Response data: {e.response_data}")
```

**Common Causes:**

- Invalid parameter values
- Missing required parameters
- Incorrect parameter types
- Invalid message format

---

### StreamParseError

Raised when parsing streaming responses fails.

```python
from fastgpt_client.exceptions import StreamParseError

try:
    for line in response.iter_lines():
        # Parse streaming data
        pass
except StreamParseError as e:
    print(f"Stream parsing error: {e.message}")
```

---

## Comprehensive Error Handling

```python
from fastgpt_client import ChatClient
from fastgpt_client.exceptions import (
    APIError,
    AuthenticationError,
    RateLimitError,
    ValidationError,
    FastGPTError
)

def safe_chat_completion(client, messages):
    """Handle chat completion with comprehensive error handling."""
    try:
        response = client.create_chat_completion(
            messages=messages,
            stream=False
        )
        response.raise_for_status()
        return response.json()

    except AuthenticationError:
        print("Error: Invalid API key. Please check your credentials.")
        return None

    except RateLimitError as e:
        print(f"Error: Rate limit exceeded. Please wait.")
        if e.retry_after:
            print(f"Retry after {e.retry_after} seconds")
        return None

    except ValidationError as e:
        print(f"Error: Invalid request parameters: {e.message}")
        return None

    except APIError as e:
        print(f"Error: API request failed: {e.message}")
        return None

    except FastGPTError as e:
        print(f"Error: Unexpected FastGPT error: {e}")
        return None

    except Exception as e:
        print(f"Error: Unexpected error: {e}")
        return None

# Usage
with ChatClient(api_key="fastgpt-xxxxx") as client:
    result = safe_chat_completion(
        client,
        [{"role": "user", "content": "Hello!"}]
    )
```

## Error Handling Best Practices

1. **Always handle exceptions** when making API calls
2. **Use specific exceptions** for better error handling
3. **Log errors** for debugging purposes
4. **Provide user-friendly messages** based on error type
5. **Implement retry logic** for rate limit errors
6. **Validate parameters** before making API calls

## Retry Logic for Rate Limiting

```python
import time
from fastgpt_client import ChatClient
from fastgpt_client.exceptions import RateLimitError

def chat_with_retry(client, messages, max_retries=3):
    """Retry chat completion on rate limit errors."""
    for attempt in range(max_retries):
        try:
            response = client.create_chat_completion(
                messages=messages,
                stream=False
            )
            response.raise_for_status()
            return response.json()

        except RateLimitError as e:
            if attempt < max_retries - 1:
                # Use Retry-After header or default delay
                delay = int(e.retry_after) if e.retry_after else 5
                print(f"Rate limited. Waiting {delay} seconds...")
                time.sleep(delay)
            else:
                print(f"Max retries exceeded. Giving up.")
                raise
```

## Next Steps

- [Error Handling Guide](../advanced/error_handling.md) - More error handling strategies
- [Rate Limiting](../advanced/rate_limiting.md) - Handling rate limits effectively