Error Handling

Understanding and handling Flameup API errors

Error Response Format

Flameup API errors use the following format:

{
  "success": false,
  "error": {
    "type": "ERROR_TYPE",
    "message": "Human-readable error message"
  },
  "request_id": "req_abc123"
}

Some endpoints may return a simplified format: {"error": "message", "message": "details"}. Check the specific endpoint documentation.

HTTP Status Codes

Flameup uses standard HTTP status codes:

Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`204`	No Content	Request succeeded (no response body)
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource doesn't exist
`409`	Conflict	Resource already exists
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server-side error
`503`	Service Unavailable	Temporary unavailability

Common Error Codes

Authentication Errors

Authentication and rate-limit failures use the flat response shape ({"error": ..., "message": ...}), not the typed error.type envelope.

HTTP Status: 401

API key is missing or invalid. Any authentication failure returns this generic 401 response.

{
  "error": "Unauthorized",
  "message": "Invalid or expired API key",
  "details": "Please provide a valid API key in the Authorization header: Bearer <your_api_key>"
}

Solutions:

Verify the API key is correct
Check the Authorization header is set with Bearer prefix
Ensure the key hasn't been revoked

Resource Errors

HTTP Status: 404

The requested resource doesn't exist. All not-found cases (including an unknown workspace) return this type.

{
  "success": false,
  "error": {
    "type": "NOT_FOUND",
    "message": "Person with ID 'xyz' not found"
  },
  "request_id": "req_abc123"
}

Solutions:

Verify the resource ID is correct
Check you're using the right workspace

Validation Errors

HTTP Status: 400

Request body or parameters failed validation. details is a string in the form field: message.

{
  "success": false,
  "error": {
    "type": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": "email: Invalid email format"
  },
  "request_id": "req_abc123"
}

Solutions:

Check the request body matches the API spec
Validate data before sending

Rate Limiting Errors

HTTP Status: 429

Too many requests in a time window. This response uses the flat shape and includes X-RateLimit-* headers.

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later."
}

Solutions:

Check the X-RateLimit-Reset header for when to retry
Implement exponential backoff
Contact support if you need a higher limit

Error Handling Best Practices

Retry Strategy

Implement exponential backoff for transient errors:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

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

      const error = await response.json();

      // Don't retry client errors (except rate limits)
      if (response.status >= 400 && response.status < 500) {
        if (response.status === 429) {
          // Rate limited - wait and retry using header
          const resetTime = parseInt(response.headers.get('X-RateLimit-Reset') || '0') * 1000;
          const waitTime = resetTime > Date.now() ? resetTime - Date.now() : 60000;
          await sleep(waitTime);
          continue;
        }
        throw new FlameupError(error);
      }

      // Server error - retry with backoff
      if (attempt < maxRetries - 1) {
        await sleep(Math.pow(2, attempt) * 1000);
        continue;
      }

      throw new FlameupError(error);

    } catch (networkError) {
      if (attempt < maxRetries - 1) {
        await sleep(Math.pow(2, attempt) * 1000);
        continue;
      }
      throw networkError;
    }
  }
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

import time
import requests

def fetch_with_retry(url, options, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.request(**options, url=url)

            if response.ok:
                return response.json()

            error = response.json()

            # Don't retry client errors (except rate limits)
            if 400 <= response.status_code < 500:
                if response.status_code == 429:
                    # Use X-RateLimit-Reset header
                    reset_time = int(response.headers.get('X-RateLimit-Reset', 0))
                    wait_time = max(reset_time - time.time(), 60) if reset_time else 60
                    time.sleep(wait_time)
                    continue
                raise FlameupError(error)

            # Server error - retry with backoff
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)
                continue

            raise FlameupError(error)

        except requests.RequestException:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)
                continue
            raise

Error Logging

Log errors with context for debugging:

function logError(error, context) {
  console.error('Flameup API Error', {
    type: error.type,
    message: error.message,
    details: error.details,
    context: {
      endpoint: context.endpoint,
      method: context.method,
      userId: context.userId,
      timestamp: new Date().toISOString()
    }
  });
}

User-Friendly Messages

Map error codes to user-friendly messages:

const ERROR_MESSAGES = {
  UNAUTHORIZED: 'Please check your API credentials',
  FORBIDDEN: 'You don\'t have permission for this action',
  NOT_FOUND: 'The requested item was not found',
  VALIDATION_ERROR: 'Please check your input and try again',
  RATE_LIMIT: 'Too many requests. Please wait a moment.',
  default: 'Something went wrong. Please try again.'
};

function getUserMessage(errorType) {
  return ERROR_MESSAGES[errorType] || ERROR_MESSAGES.default;
}

Debugging Tips

Use these tips to debug API issues:

Check the response body - Error details are always in the response
Verify API key permissions - Most 403 errors are permission issues
Validate request format - Use the API reference for correct schemas
Check rate limit headers - Monitor X-RateLimit-* headers (returned on 429 responses)
Include the request ID - Provide the request_id from error responses when contacting support

Was this page helpful?