API-Referenz

Complete troubleshooting guide for common issues with the LISA REST API.

Common Issues#

Authentication Problems#

1. 401 Unauthorized - Missing Token#

Symptoms:

• Getting 401 Unauthorized with "Authorization header is required" error
• All API requests fail with authentication errors

Solutions:

# Check if you're including the Authorization header
curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/health"

# Generate a new token if you don't have one
curl -X POST "https://api.biocv.info/api/v1/tokens" \
  -H "Content-Type: application/json" \
  -d '{"integratorUID": "your-integrator-uid", "expiresIn": 3600, "refreshToken": true}'

Debug Steps:

1. Verify you have a valid JWT token
2. Check the Authorization header format: Bearer <token>
3. Ensure there's a space after "Bearer"
4. Test token validity with /tokens/validate

2. 401 Unauthorized - Invalid Token#

Symptoms:

• Getting "Invalid token" error
• Token appears to be malformed

Solutions:

# Validate your token
curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/tokens/validate"

# Generate a new token
curl -X POST "https://api.biocv.info/api/v1/tokens" \
  -H "Content-Type: application/json" \
  -d '{"integratorUID": "your-integrator-uid", "expiresIn": 3600}'

Debug Steps:

1. Check token format (should be JWT format)
2. Verify token wasn't truncated or modified
3. Ensure token is from the correct API instance
4. Check if token has expired

3. 401 Unauthorized - Expired Token#

Symptoms:

• Getting "Token has expired" error
• Token was working before but now fails

Solutions:

// Check token expiration
function isTokenExpired(token) {
  try {
    const payload = JSON.parse(atob(token.split('.')[1]));
    return Date.now() >= payload.exp * 1000;
  } catch (error) {
    return true; // Invalid token format
  }
}

// Refresh token
async function refreshToken() {
  const response = await fetch('/api/v1/tokens/refresh', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ refreshToken: refreshToken })
  });
  
  const data = await response.json();
  if (data.success) {
    accessToken = data.data.accessToken;
    refreshToken = data.data.refreshToken;
  }
}

4. 403 Forbidden - Invalid Integrator#

Symptoms:

• Getting "Access denied: Invalid integratorUID" error
• Token generation fails

Solutions:

# Test integrator UID
curl -X POST "https://api.biocv.info/api/v1/tokens" \
  -H "Content-Type: application/json" \
  -d '{"integratorUID": "your-integrator-uid", "expiresIn": 3600}'

# Contact LISA team if integrator is invalid

Debug Steps:

1. Verify integrator UID is correct
2. Check if integrator is active in the system
3. Contact LISA team to verify integrator status
4. Ensure integrator has proper permissions

Data Access Problems#

1. 404 Not Found - User Not Found#

Symptoms:

• Getting "User not found" error
• Cannot access user data

Solutions:

# Verify user exists
curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123"

# Check if user ID is correct
curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/search?email=user@example.com"

Debug Steps:

1. Verify user ID is correct
2. Check if user exists in the system
3. Ensure user ID format is correct
4. Verify integrator has access to this user

2. 404 Not Found - Resource Not Found#

Symptoms:

• Getting "Animal not found" or similar errors
• Specific resources cannot be accessed

Solutions:

# List all resources first
curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals"

# Search for specific resource
curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/search?mac=AA:BB:CC:DD:EE:FF"

Debug Steps:

1. Verify resource ID is correct
2. Check if resource exists
3. Ensure resource belongs to the user
4. Use search endpoints to find resources

Validation Errors#

1. 400 Bad Request - Validation Failed#

Symptoms:

• Getting validation error messages
• Request data is rejected

Solutions:

// Validate data before sending
function validateAnimalData(data) {
  const errors = [];
  
  if (!data.ID) errors.push('ID is required');
  if (!data.MAC) errors.push('MAC is required');
  if (!['male', 'female'].includes(data.Sex)) {
    errors.push('Sex must be male or female');
  }
  
  return errors;
}

// Check validation errors in response
if (response.status === 400 && data.details) {
  data.details.forEach(detail => {
    console.error(`Field ${detail.field}: ${detail.message}`);
  });
}

Debug Steps:

1. Check required fields are present
2. Verify field formats (MAC address, email, etc.)
3. Check field value ranges
4. Review API documentation for requirements

2. 400 Bad Request - Invalid Query Parameters#

Symptoms:

• Getting "Invalid limit" or similar errors
• Query parameters are rejected

Solutions:

# Use valid parameter ranges
curl "https://api.biocv.info/api/v1/users/user123/animals?page=1&limit=50"

# Check parameter requirements
curl "https://api.biocv.info/api/v1/users/user123/animals/search?sex=female&active=true"

Debug Steps:

1. Check parameter value ranges (limit: 1-100)
2. Verify parameter names are correct
3. Check parameter formats
4. Review endpoint documentation

Rate Limiting Issues#

1. 429 Too Many Requests#

Symptoms:

• Getting "Too many requests" error
• API calls are being throttled

Solutions:

// Implement exponential backoff
async function makeRequestWithRetry(url, options = {}, retries = 3) {
  for (let attempt = 1; attempt <= retries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        if (attempt < retries) {
          const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
          await new Promise(resolve => setTimeout(resolve, delay));
          continue;
        }
      }
      
      return response;
    } catch (error) {
      if (attempt === retries) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }
}

// Monitor rate limit headers
function checkRateLimit(response) {
  const remaining = response.headers.get('X-RateLimit-Remaining');
  const reset = response.headers.get('X-RateLimit-Reset');
  
  console.log(`Rate limit: ${remaining} remaining, resets at ${new Date(reset * 1000)}`);
}

Debug Steps:

1. Check rate limit headers in response
2. Implement proper backoff strategy
3. Reduce request frequency
4. Monitor API usage patterns

Network Issues#

1. Connection Timeouts#

Symptoms:

• Requests timeout
• Network errors

Solutions:

// Set appropriate timeouts
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30000); // 30 seconds

fetch(url, {
  signal: controller.signal,
  // ... other options
}).finally(() => clearTimeout(timeoutId));

// Implement retry logic
async function makeRequestWithRetry(url, options = {}, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      return response;
    } catch (error) {
      if (attempt === maxRetries) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
    }
  }
}

Debug Steps:

1. Check network connectivity
2. Verify API endpoint is accessible
3. Check firewall settings
4. Test with different networks

2. DNS Resolution Issues#

Symptoms:

• Cannot resolve API hostname
• DNS errors

Solutions:

# Test DNS resolution
nslookup api.biocv.info

# Test connectivity
ping api.biocv.info

# Check with different DNS servers
nslookup api.biocv.info 8.8.8.8

Debug Steps:

1. Check DNS configuration
2. Try different DNS servers
3. Check network connectivity
4. Verify hostname is correct

Debugging Tools#

API Testing Tools#

cURL Debugging#

# Verbose output for debugging
curl -v -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/health"

# Check response headers
curl -I -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/health"

# Test with different methods
curl -X POST -H "Authorization: Bearer your-jwt-token" \
     -H "Content-Type: application/json" \
     -d '{"integratorUID": "test"}' \
     "https://api.biocv.info/api/v1/tokens"

Postman Collection#

{
  "info": {
    "name": "LISA API",
    "description": "Complete LISA API collection"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://api.biocv.info/api/v1"
    },
    {
      "key": "accessToken",
      "value": "{{accessToken}}"
    }
  ],
  "item": [
    {
      "name": "Health Check",
      "request": {
        "method": "GET",
        "url": "{{baseUrl}}/health"
      }
    },
    {
      "name": "Generate Token",
      "request": {
        "method": "POST",
        "url": "{{baseUrl}}/tokens",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"integratorUID\": \"your-integrator-uid\",\n  \"expiresIn\": 3600,\n  \"refreshToken\": true\n}"
        }
      }
    }
  ]
}

Logging and Monitoring#

Request Logging#

class LoggingAPIClient {
  constructor(apiClient, logger) {
    this.apiClient = apiClient;
    this.logger = logger;
  }

  async makeRequest(endpoint, options = {}) {
    const startTime = Date.now();
    const requestId = Math.random().toString(36).substr(2, 9);
    
    this.logger.info('API request started', {
      requestId,
      endpoint,
      method: options.method || 'GET',
      timestamp: new Date().toISOString()
    });

    try {
      const result = await this.apiClient.makeRequest(endpoint, options);
      
      this.logger.info('API request completed', {
        requestId,
        endpoint,
        duration: Date.now() - startTime,
        status: 'success'
      });
      
      return result;
    } catch (error) {
      this.logger.error('API request failed', {
        requestId,
        endpoint,
        duration: Date.now() - startTime,
        error: error.message,
        status: 'error'
      });
      
      throw error;
    }
  }
}

Performance Monitoring#

class PerformanceMonitor {
  constructor() {
    this.metrics = {
      requests: 0,
      errors: 0,
      totalDuration: 0,
      averageResponseTime: 0
    };
  }

  recordRequest(duration, success) {
    this.metrics.requests++;
    this.metrics.totalDuration += duration;
    this.metrics.averageResponseTime = this.metrics.totalDuration / this.metrics.requests;
    
    if (!success) {
      this.metrics.errors++;
    }
  }

  getMetrics() {
    return {
      ...this.metrics,
      errorRate: this.metrics.requests > 0 ? this.metrics.errors / this.metrics.requests : 0
    };
  }
}

Common Error Messages#

Authentication Errors#

• "Authorization header is required" - Missing Authorization header
• "Invalid authorization header format" - Malformed Authorization header
• "Token has expired" - JWT token has expired
• "Invalid token" - Token is malformed or invalid
• "Access denied: Invalid integratorUID" - Invalid integrator UID

Validation Errors#

• "integratorUID is required" - Missing required field
• "Invalid limit. Must be a number between 1 and 100" - Invalid parameter value
• "Invalid date format. Use ISO 8601 format" - Invalid date format
• "Invalid classification type. Must be heat, birth, or lameness" - Invalid enum value

Resource Errors#

• "User not found" - User doesn't exist
• "Animal not found" - Animal doesn't exist
• "Treatment not found" - Treatment doesn't exist
• "LitterGuard device not found" - Device doesn't exist

Rate Limiting Errors#

• "Too many requests from this IP, please try again later" - Rate limit exceeded
• "Too many token requests from this IP, please try again later" - Token rate limit exceeded

Getting Help#

Before Contacting Support#

1. Check this troubleshooting guide for your specific error
2. Test with cURL to isolate the issue
3. Check API status at the health endpoint
4. Verify your configuration (integrator UID, base URL, etc.)
5. Review recent changes to your code or configuration

Information to Include#

When contacting support, include:

1. Error message and HTTP status code
2. Request details (endpoint, method, headers)
3. Response body (if any)
4. Steps to reproduce the issue
5. Your integrator UID (for authentication issues)
6. Timestamp when the issue occurred

Support Channels#

• Email: Contact the LISA Development Team
• Documentation: Check the main README.md
• API Reference: Review the endpoints documentation

This troubleshooting guide should help you resolve most common issues with the LISA REST API. If you continue to experience problems, please contact the LISA Development Team with the information outlined above.