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

{
  "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

{
  "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

{
  "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

{
  "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

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 →