Error Codes

This page documents all error codes returned by the FinBrain API and how to handle them in your application.

Error Response Format

All errors are returned as JSON with the following structure:

{
  "error": "Error Type",
  "message": "Human-readable error description"
}

HTTP Status Codes

400 Bad Request

The request is malformed or contains invalid parameters.

{
  "error": "Bad Request",
  "message": "Invalid ticker symbol: XYZ123"
}

Python SDK Exception: BadRequest

Common causes:

• Invalid ticker symbol
• Invalid market identifier
• Invalid prediction type (not daily or monthly)
• Malformed date parameters

How to fix:

• Verify the ticker symbol exists using /available/tickers
• Check the market name using /available/markets
• Ensure dates are in YYYY-MM-DD format

401 Unauthorized

API key missing or invalid.

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

Python SDK Exception: AuthenticationError

Common causes:

• Missing token query parameter
• Invalid API key
• Expired API key
• Typo in API key

How to fix:

• Ensure the token parameter is included in every request
• Verify your API key is correct
• Check your account dashboard for key status

403 Forbidden

Authenticated, but not authorised to perform this action.

{
  "error": "Forbidden",
  "message": "Access denied for this resource"
}

Python SDK Exception: PermissionDenied

Common causes:

• Endpoint not included in your subscription tier
• Account suspended
• Accessing a premium endpoint with a free tier key

How to fix:

• Check your subscription tier and available endpoints
• Upgrade your subscription if needed
• Contact support if you believe this is an error

404 Not Found

Requested data or endpoint not found.

{
  "error": "Not Found",
  "message": "Ticker INVALID not found in market S&P 500"
}

Python SDK Exception: NotFound

Common causes:

• Ticker doesn’t exist in the specified market
• Endpoint path is incorrect
• Data not available for the specified date range

How to fix:

• Verify the ticker exists using /available/tickers
• Check the endpoint path in the API reference
• Try a different date range

405 Method Not Allowed

Endpoint exists, but the HTTP method is not supported.

{
  "error": "Method Not Allowed",
  "message": "POST method not supported for this endpoint"
}

Python SDK Exception: MethodNotAllowed

Common causes:

• Using POST instead of GET
• Using PUT, DELETE, or PATCH on read-only endpoints

How to fix:

• All FinBrain API endpoints use GET requests
• Change your HTTP method to GET

500 Internal Server Error

Internal error on FinBrain’s side. Retrying later may help.

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Python SDK Exception: ServerError

Common causes:

• Server-side issues
• Database connectivity problems
• Temporary service disruption

How to fix:

• Retry the request after a short delay
• Check FinBrain status page for outages
• Contact support if the issue persists

Error Handling Examples

Python

from finbrain import FinBrainClient
from finbrain.exceptions import (
    AuthenticationError,
    NotFound,
    ServerError,
    FinBrainError
)
import time

fb = FinBrainClient(api_key="YOUR_API_KEY")

def get_predictions_with_retry(ticker, max_retries=3):
    """Get predictions with automatic retry on failure"""
    for attempt in range(max_retries):
        try:
            return fb.predictions.ticker(ticker, prediction_type="daily")
        except AuthenticationError:
            # Auth error - don't retry
            raise Exception("Invalid API key")
        except NotFound:
            # Not found - don't retry
            raise Exception(f"Ticker {ticker} not found")
        except ServerError:
            # Server error - retry with backoff
            if attempt == max_retries - 1:
                raise
            wait_time = 2 ** attempt
            print(f"Server error. Retrying in {wait_time}s...")
            time.sleep(wait_time)
        except FinBrainError:
            # Other API error - retry
            if attempt == max_retries - 1:
                raise
            time.sleep(1)

    raise Exception("Max retries exceeded")

# Usage
try:
    data = get_predictions_with_retry("AAPL")
    print(data)
except Exception as e:
    print(f"Error: {e}")

JavaScript

const API_KEY = "YOUR_API_KEY";

async function getPredictionsWithRetry(ticker, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(
        `https://api.finbrain.tech/v1/ticker/${ticker}/predictions/daily?token=${API_KEY}`
      );

      if (response.ok) {
        return await response.json();
      }

      if (response.status === 401) {
        throw new Error("Invalid API key");
      }

      if (response.status === 404) {
        throw new Error(`Ticker ${ticker} not found`);
      }

      if (response.status === 500) {
        // Server error - retry with backoff
        if (attempt === maxRetries - 1) {
          throw new Error("Server error");
        }
        const waitTime = Math.pow(2, attempt) * 1000;
        console.log(`Server error. Retrying in ${waitTime}ms...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }

      // Other error - don't retry
      throw new Error(`HTTP ${response.status}`);

    } catch (error) {
      if (attempt === maxRetries - 1) {
        throw error;
      }
    }
  }
  throw new Error("Max retries exceeded");
}

// Usage
try {
  const data = await getPredictionsWithRetry("AAPL");
  console.log(data);
} catch (error) {
  console.error("Error:", error.message);
}

Python SDK Exception Classes

The Python SDK provides typed exceptions for each error code:

Exception	HTTP Status	Description
BadRequest	400	The request is malformed or contains invalid parameters
AuthenticationError	401	API key missing or invalid
PermissionDenied	403	Authenticated, but not authorised to perform this action
NotFound	404	Requested data or endpoint not found
MethodNotAllowed	405	Endpoint exists, but the HTTP method is not supported
ServerError	500	Internal error on FinBrain’s side
InvalidResponse	N/A	Response couldn’t be parsed as JSON
FinBrainError	N/A	Base class for all SDK exceptions

Best Practices

1. Always check status codes - Don’t assume success
2. Implement retry logic - Use exponential backoff for 500 errors
3. Cache responses - Reduce API calls by caching data locally
4. Validate inputs - Check ticker symbols before making requests
5. Handle errors gracefully - Provide meaningful error messages to users

Related Documentation

• Authentication
• API Reference Overview
• Python SDK