Error Handling | Bootspring Docs

Comprehensive guide to handling API errors in Bootspring.

Error Response Format#

All errors follow a consistent JSON format:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ],
    "request_id": "req_abc123"
  }
}

HTTP Status Codes#

Status	Description
400	Bad Request - Invalid request body or parameters
401	Unauthorized - Missing or invalid authentication
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
409	Conflict - Resource already exists
422	Unprocessable Entity - Validation failed
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server-side error
502	Bad Gateway - Upstream service error
503	Service Unavailable - Temporarily unavailable

Error Codes Reference#

Authentication Errors (401)#

Code	Message
`unauthorized`	Missing or invalid authentication token
`token_expired`	The authentication token has expired
`token_revoked`	The authentication token has been revoked
`invalid_api_key`	The API key is invalid or inactive
`api_key_expired`	The API key has expired

Permission Errors (403)#

Code	Message
`forbidden`	You don't have permission to access this resource
`insufficient_scope`	Token lacks required scope
`tier_required`	This feature requires a higher tier
`quota_exceeded`	You've exceeded your plan's quota

Validation Errors (400, 422)#

Code	Message
`invalid_request`	The request body is invalid
`validation_failed`	One or more fields failed validation
`missing_field`	A required field is missing
`invalid_field`	A field has an invalid value
`invalid_json`	The request body is not valid JSON

Resource Errors (404, 409)#

Code	Message
`not_found`	The requested resource was not found
`already_exists`	A resource with this identifier already exists
`deleted`	The resource has been deleted

Rate Limiting Errors (429)#

Code	Message
`rate_limited`	Too many requests, please slow down
`concurrent_limit`	Too many concurrent requests

Server Errors (5xx)#

Code	Message
`internal_error`	An internal server error occurred
`service_unavailable`	The service is temporarily unavailable
`upstream_error`	An upstream service returned an error
`timeout`	The request timed out

Handling Errors#

JavaScript/TypeScript#

class BootspringError extends Error {
  code: string;
  status: number;
  details?: Array<{ field: string; message: string }>;
  requestId?: string;

  constructor(response: ErrorResponse, status: number) {
    super(response.error.message);
    this.name = 'BootspringError';
    this.code = response.error.code;
    this.status = status;
    this.details = response.error.details;
    this.requestId = response.error.request_id;
  }

  isRetryable(): boolean {
    return [429, 500, 502, 503].includes(this.status);
  }
}

async function apiRequest(url: string, options: RequestInit) {
  const response = await fetch(url, options);

  if (!response.ok) {
    const data = await response.json();
    throw new BootspringError(data, response.status);
  }

  return response.json();
}

// Usage
try {
  const projects = await apiRequest('/api/projects', {
    headers: { Authorization: `Bearer ${token}` },
  });
} catch (error) {
  if (error instanceof BootspringError) {
    switch (error.code) {
      case 'unauthorized':
        // Redirect to login
        break;
      case 'token_expired':
        // Refresh token and retry
        break;
      case 'rate_limited':
        // Wait and retry
        break;
      case 'validation_failed':
        // Show field errors
        error.details?.forEach((d) => {
          console.log(`${d.field}: ${d.message}`);
        });
        break;
      default:
        // Show generic error
        console.error(error.message);
    }
  }
}

Python#

import requests
from typing import Optional, List, Dict

class BootspringError(Exception):
    def __init__(self, response: dict, status_code: int):
        error = response.get('error', {})
        super().__init__(error.get('message', 'Unknown error'))
        self.code = error.get('code')
        self.status = status_code
        self.details = error.get('details', [])
        self.request_id = error.get('request_id')

    def is_retryable(self) -> bool:
        return self.status in [429, 500, 502, 503]

def api_request(url: str, method: str = 'GET', **kwargs):
    response = requests.request(method, url, **kwargs)

    if not response.ok:
        raise BootspringError(response.json(), response.status_code)

    return response.json()

# Usage
try:
    projects = api_request(
        'https://api.bootspring.dev/v1/projects',
        headers={'Authorization': f'Bearer {token}'}
    )
except BootspringError as e:
    if e.code == 'unauthorized':
        # Handle auth error
        pass
    elif e.code == 'rate_limited':
        # Wait and retry
        pass
    else:
        print(f"Error: {e.message}")

Validation Error Details#

When validation fails, the details array provides specific information:

{
  "error": {
    "code": "validation_failed",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "code": "invalid_email"
      },
      {
        "field": "name",
        "message": "Name must be between 2 and 100 characters",
        "code": "string_length",
        "min": 2,
        "max": 100
      },
      {
        "field": "tags",
        "message": "Maximum 10 tags allowed",
        "code": "array_max_length",
        "max": 10
      }
    ]
  }
}

Field Validation Codes#

Code	Description
`required`	Field is required
`invalid_type`	Field has wrong type
`invalid_email`	Not a valid email
`invalid_url`	Not a valid URL
`string_length`	String length out of bounds
`number_range`	Number out of range
`array_max_length`	Array too long
`invalid_enum`	Value not in allowed list
`pattern_mismatch`	Value doesn't match pattern

Retry Strategies#

Exponential Backoff#

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries: number = 3,
  baseDelay: number = 1000
): Promise<T> {
  let lastError: Error;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error as Error;

      if (error instanceof BootspringError) {
        // Don't retry non-retryable errors
        if (!error.isRetryable()) {
          throw error;
        }

        // Use Retry-After header if available
        const retryAfter = error.retryAfter;
        const delay = retryAfter
          ? retryAfter * 1000
          : baseDelay * Math.pow(2, attempt);

        await sleep(delay);
      } else {
        throw error;
      }
    }
  }

  throw lastError!;
}

Circuit Breaker#

class CircuitBreaker {
  private failures = 0;
  private lastFailure: number = 0;
  private state: 'closed' | 'open' | 'half-open' = 'closed';

  constructor(
    private threshold: number = 5,
    private resetTimeout: number = 60000
  ) {}

  async execute<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === 'open') {
      if (Date.now() - this.lastFailure > this.resetTimeout) {
        this.state = 'half-open';
      } else {
        throw new Error('Circuit breaker is open');
      }
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  private onSuccess(): void {
    this.failures = 0;
    this.state = 'closed';
  }

  private onFailure(): void {
    this.failures++;
    this.lastFailure = Date.now();

    if (this.failures >= this.threshold) {
      this.state = 'open';
    }
  }
}

Error Logging#

Include the request_id when reporting issues:

try {
  await apiRequest('/api/projects');
} catch (error) {
  if (error instanceof BootspringError) {
    console.error('API Error:', {
      code: error.code,
      message: error.message,
      requestId: error.requestId,
      status: error.status,
    });

    // Report to error tracking service
    Sentry.captureException(error, {
      extra: {
        requestId: error.requestId,
        code: error.code,
      },
    });
  }
}

Debugging#

Request Headers#

Include these headers for debugging:

curl -X GET https://api.bootspring.dev/v1/projects \
  -H "Authorization: Bearer bs_xxx" \
  -H "X-Request-Id: my-debug-id" \
  -H "X-Debug: true"

Debug Mode Response#

With X-Debug: true, responses include additional information:

{
  "data": { ... },
  "debug": {
    "request_id": "req_abc123",
    "duration_ms": 45,
    "region": "us-east-1",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}