> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fincept.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Complete guide to error codes, handling strategies, and troubleshooting

# Error Handling

Comprehensive guide to handling errors in Fincept API, including error codes, retry strategies, and debugging.

## Error Response Structure

```json theme={null}
{
  "success": false,
  "message": "Brief error summary",
  "detail": "Detailed explanation with context"
}
```

## HTTP Status Codes

### 4xx Client Errors

| Code    | Error            | Cause                  | Solution                |
| ------- | ---------------- | ---------------------- | ----------------------- |
| **400** | Bad Request      | Invalid parameters     | Check request body      |
| **401** | Unauthorized     | Invalid API key        | Verify key, login again |
| **402** | Payment Required | Insufficient credits   | Purchase credits        |
| **403** | Forbidden        | Tier access needed     | Upgrade plan            |
| **404** | Not Found        | Endpoint doesn't exist | Check URL               |
| **429** | Rate Limit       | Too many requests      | Wait and retry          |

### 5xx Server Errors

| Code    | Error               | Cause        | Solution               |
| ------- | ------------------- | ------------ | ---------------------- |
| **500** | Internal Error      | Server issue | Retry, contact support |
| **503** | Service Unavailable | Maintenance  | Check status page      |

## Common Errors

### Insufficient Credits

```json theme={null}
{
  "success": false,
  "message": "Insufficient credits",
  "detail": "Required: 5 credits, Available: 2 credits. Please purchase a new plan to continue."
}
```

**Solution:** Purchase credits or subscribe

### Invalid API Key

```json theme={null}
{
  "success": false,
  "message": "Invalid or expired API key"
}
```

**Solutions:**

* Login to retrieve current key
* Check for typos
* Verify key wasn't regenerated
* For guests, check expiry

### Rate Limit Exceeded

```json theme={null}
{
  "success": false,
  "message": "Rate limit exceeded"
}
```

**Response headers:**

```
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640998800
Retry-After: 3600
```

## Retry Strategies

### Exponential Backoff

```python theme={null}
import time
import requests

def api_call_with_retry(url, data, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=data, headers=headers)

            if response.status_code == 200:
                return response.json()

            elif response.status_code == 429:
                # Rate limited - wait and retry
                retry_after = int(response.headers.get("Retry-After", 60))
                time.sleep(retry_after)
                continue

            elif response.status_code >= 500:
                # Server error - exponential backoff
                wait_time = (2 ** attempt) * 1
                time.sleep(wait_time)
                continue

            else:
                # Client error - don't retry
                return response.json()

        except requests.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

    raise Exception("Max retries exceeded")
```

[Complete examples →](/advanced-workflows)