Error Codes

All IndepAI API errors follow a consistent format. This page documents all error codes and provides guidance on handling them.

Error Response Format

{
  "success": false,
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "details": [
    {
      "path": "fieldName",
      "message": "Specific error for this field"
    }
  ]
}

HTTP Status Codes

Status	Meaning	When It Occurs
400	Bad Request	Invalid input, validation failure
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Valid auth but insufficient permissions
404	Not Found	Resource doesn’t exist
409	Conflict	Resource already exists or state conflict
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error
503	Service Unavailable	Service temporarily down

Error Codes Reference

Authentication Errors (401)

UNAUTHORIZED

Missing or invalid authentication token.

{
  "success": false,
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}

Solution: Include a valid Bearer token in the Authorization header.

curl -H "Authorization: Bearer YOUR_TOKEN" ...

TOKEN_EXPIRED

The JWT token has expired.

{
  "success": false,
  "error": "Token has expired",
  "code": "TOKEN_EXPIRED"
}

Solution: Refresh your token using the refresh token.

Authorization Errors (403)

FORBIDDEN

User doesn’t have permission for this action.

{
  "success": false,
  "error": "Access denied",
  "code": "FORBIDDEN"
}

Solution: Check user permissions or upgrade subscription tier.

SUBSCRIPTION_REQUIRED

Endpoint requires a paid subscription.

{
  "success": false,
  "error": "This feature requires a Pro subscription",
  "code": "SUBSCRIPTION_REQUIRED"
}

Solution: Upgrade your subscription at /settings/billing.

Validation Errors (400)

VALIDATION_ERROR

Request body failed validation.

{
  "success": false,
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": [
    { "path": "currentAge", "message": "Must be between 18 and 100" },
    { "path": "annualExpenses", "message": "Must be greater than 0" }
  ]
}

Solution: Fix the fields indicated in details.

INVALID_JSON

Request body is not valid JSON.

{
  "success": false,
  "error": "Invalid JSON in request body",
  "code": "INVALID_JSON"
}

Solution: Ensure your request body is valid JSON.

MISSING_FIELD

A required field is missing.

{
  "success": false,
  "error": "Missing required field: annualIncome",
  "code": "MISSING_FIELD"
}

Solution: Include all required fields in your request.

Resource Errors (404)

NOT_FOUND

The requested resource doesn’t exist.

{
  "success": false,
  "error": "Asset not found",
  "code": "NOT_FOUND"
}

Solution: Verify the resource ID exists.

ENDPOINT_NOT_FOUND

The API endpoint doesn’t exist.

{
  "success": false,
  "error": "Endpoint not found",
  "code": "ENDPOINT_NOT_FOUND"
}

Solution: Check the API documentation for correct endpoint paths.

Conflict Errors (409)

CONFLICT

Operation conflicts with current state.

{
  "success": false,
  "error": "Asset with this ISIN already exists",
  "code": "CONFLICT"
}

Solution: Use a unique identifier or update the existing resource.

Rate Limit Errors (429)

RATE_LIMITED

Too many requests in the time window.

{
  "success": false,
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "retryAfter": 3600
}

Solution: Wait for retryAfter seconds or upgrade your tier.

Server Errors (500)

INTERNAL_ERROR

An unexpected error occurred.

{
  "success": false,
  "error": "Internal server error",
  "code": "INTERNAL_ERROR"
}

Solution: Retry after a moment. If persistent, contact support.

DATABASE_ERROR

Database operation failed.

{
  "success": false,
  "error": "Database operation failed",
  "code": "DATABASE_ERROR"
}

Solution: Retry after a moment. This is usually temporary.

Service Errors (503)

SERVICE_UNAVAILABLE

The service is temporarily unavailable.

{
  "success": false,
  "error": "Service temporarily unavailable",
  "code": "SERVICE_UNAVAILABLE"
}

Solution: Retry with exponential backoff.

Handling Errors

JavaScript/TypeScript

async function callAPI(endpoint: string, body: object) {
  const response = await fetch(`https://indepai.app/api/v1/${endpoint}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify(body),
  });

  const data = await response.json();

  if (!data.success) {
    switch (data.code) {
      case "VALIDATION_ERROR":
        // Show field-specific errors
        data.details?.forEach((err) => {
          showFieldError(err.path, err.message);
        });
        break;

      case "UNAUTHORIZED":
      case "TOKEN_EXPIRED":
        // Redirect to login
        redirectToLogin();
        break;

      case "RATE_LIMITED":
        // Show rate limit message
        showError(`Too many requests. Try again in ${data.retryAfter} seconds.`);
        break;

      case "INTERNAL_ERROR":
      case "DATABASE_ERROR":
        // Generic error with retry
        showError("Something went wrong. Please try again.");
        break;

      default:
        showError(data.error);
    }
    throw new Error(data.error);
  }

  return data;
}

Python

import requests

def call_api(endpoint, body):
    response = requests.post(
        f"https://indepai.app/api/v1/{endpoint}",
        json=body,
        headers={"Authorization": f"Bearer {token}"}
    )

    data = response.json()

    if not data.get("success"):
        code = data.get("code")

        if code == "VALIDATION_ERROR":
            for detail in data.get("details", []):
                print(f"Field {detail['path']}: {detail['message']}")
        elif code == "RATE_LIMITED":
            retry_after = data.get("retryAfter", 60)
            print(f"Rate limited. Retry in {retry_after} seconds")
        else:
            print(f"Error: {data.get('error')}")

        raise Exception(data.get("error"))

    return data

Common Mistakes

1. Missing Content-Type Header

# Wrong
curl -X POST /api/v1/calculator -d '{"currentAge": 30}'

# Correct
curl -X POST /api/v1/calculator \
  -H "Content-Type: application/json" \
  -d '{"currentAge": 30}'

2. Wrong Authentication Format

# Wrong
curl -H "Authorization: YOUR_TOKEN" ...

# Correct
curl -H "Authorization: Bearer YOUR_TOKEN" ...

3. Using Strings Instead of Numbers

// Wrong
{ "currentAge": "30", "annualIncome": "80000" }

// Correct
{ "currentAge": 30, "annualIncome": 80000 }

Getting Help

If you encounter an error not listed here or need assistance:

1. Check the API Reference for correct endpoint usage
2. Review your request against the examples in guides
3. Contact support@indepai.app with:
   • The full error response
   • Your request (without sensitive data)
   • Timestamp of the request