Common Issues and Solutions

Troubleshooting guide for common SCORM API issues and their solutions.

Table of Contents

• Authentication Issues
• Package Upload Issues
• Session Issues
• Player Issues
• API Errors
• Performance Issues

Authentication Issues

Error: "Invalid API Key"

Symptoms:

• 401 Unauthorized responses
• "Invalid API Key" error message

Solutions:

1. Verify API Key:

   # Test your API key
   curl -X GET https://app.allureconnect.com/api/health \
     -H "X-API-Key: your-api-key-here"
   

2. Check Key Format:

   • API keys start with scorm_
   • Keys are long (64+ characters)
   • No spaces or line breaks

3. Verify Header:

   • Use X-API-Key header
   • Or Authorization: Bearer your-api-key
   • Case-sensitive

4. Check Key Status:

   • Verify key is active in dashboard
   • Check if key has expired
   • Verify key hasn't been revoked

5. Regenerate Key:

   • If key is compromised, generate new one
   • Update all integrations
   • Revoke old key

Error: "Tenant Mismatch"

Symptoms:

• 403 Forbidden responses
• "Tenant mismatch" error

Solutions:

1. Verify Tenant ID:

   • Check tenant ID matches API key
   • Ensure tenant ID is correct UUID format
   • Verify tenant exists

2. Check API Key Scope:

   • Verify key has required scopes
   • Check key belongs to correct tenant
   • Verify tenant isolation

3. Update Request:

   • Include correct tenant_id in requests
   • Or let API key determine tenant automatically

Package Upload Issues

Error: "File Too Large"

Symptoms:

• 413 Payload Too Large
• "File too large" error message

Solutions:

1. Check File Size:

   • Default limit: 100MB
   • Maximum: 10GB (with multipart upload)
   • Verify actual file size

2. Use Multipart Upload:

   // For files >100MB, use multipart upload
   // See: docs/getting-started/first-package.md
   

3. Check Quota:

   • Verify storage quota not exceeded
   • Check package count limit
   • Upgrade plan if needed

4. Compress Package:

   • Remove unnecessary files
   • Optimize media files
   • Use efficient compression

Error: "Invalid SCORM Package"

Symptoms:

• 400 Bad Request
• "Invalid SCORM package" error

Solutions:

1. Verify Package Structure:

   • Must contain imsmanifest.xml
   • Must be valid ZIP archive
   • Check file integrity

2. Check SCORM Version:

   • Supported: SCORM 1.2 and SCORM 2004
   • Verify manifest version
   • Check schema compliance

3. Validate Package:

   • Use SCORM validation tools
   • Test in SCORM test suite
   • Check manifest syntax

4. Review Error Details:

   • Check error response for specifics
   • Look for manifest errors
   • Verify file paths

Error: "Package Processing Failed"

Symptoms:

• Processing timeout
• Processing error message

Solutions:

1. Check Package Size:

   • Large packages take longer
   • Allow 5-10 minutes for processing
   • Monitor processing status

2. Verify Storage:

   • Check storage backend status
   • Verify storage quota
   • Check network connectivity

3. Retry Upload:

   • Wait and retry
   • Check for temporary issues
   • Contact support if persistent

4. Check Package Content:

   • Verify all files present
   • Check for corrupted files
   • Validate ZIP integrity

Session Issues

Error: "Session Not Found"

Symptoms:

• 404 Not Found
• "Session not found" error

Solutions:

1. Verify Session ID:

   • Check session ID format (UUID)
   • Ensure session ID is correct
   • Verify session exists

2. Check Session Expiration:

   • Sessions expire after inactivity
   • Default: 24 hours
   • Create new session if expired

3. Verify Tenant:

   • Ensure session belongs to your tenant
   • Check API key tenant matches
   • Verify tenant isolation

4. Check Session Status:

   • Verify session is active
   • Check if session was deleted
   • Review session history

Error: "Version Conflict" (409)

Symptoms:

• 409 Conflict
• "Version conflict" error

Solutions:

1. Implement Retry Logic:

   async function updateSessionWithRetry(sessionId, updates, maxRetries = 3) {
     for (let attempt = 0; attempt < maxRetries; attempt++) {
       // Get current session
       const session = await getSession(sessionId);
       
       // Merge updates
       const payload = {
         version: session.version,
         ...updates
       };
       
       // Attempt update
       const response = await updateSession(sessionId, payload);
       
       if (response.ok) return response.json();
       if (response.status === 409 && attempt < maxRetries - 1) {
         await delay(100 * (attempt + 1)); // Exponential backoff
         continue;
       }
       throw new Error('Update failed');
     }
   }
   

2. Fetch Latest Version:

   • Always get latest session before update
   • Use current version number
   • Merge your changes with latest

3. Handle Concurrent Updates:

   • Implement optimistic locking
   • Use version numbers correctly
   • Retry with fresh data

Player Issues

Player Not Loading

Symptoms:

• Blank iframe
• Loading spinner never completes
• Error in browser console

Solutions:

1. Check CORS Configuration:

   • Verify CORS headers
   • Check allowed origins
   • Test from different domains

2. Verify Session:

   • Check session is valid
   • Verify session hasn't expired
   • Ensure session is active

3. Check Network:

   • Verify network connectivity
   • Check firewall rules
   • Test from different network

4. Browser Console:

   • Check for JavaScript errors
   • Verify console messages
   • Look for network errors

5. Test Launch URL:

   # Use the full launch_url returned by /api/v1/packages/:id/launch —
   # it already contains the signed ?token=<jwt>. A bare
   # /player/:sessionId without ?token= will always return HTTP 401.
   curl "https://app.allureconnect.com/player/session-123?token=<jwt-from-launch-response>"
   

Content Not Displaying

Symptoms:

• Player loads but content blank
• Missing resources
• Broken links

Solutions:

1. Check Package Files:

   • Verify all files uploaded
   • Check file paths in manifest
   • Verify relative paths

2. Check Storage:

   • Verify files in storage
   • Check storage permissions
   • Verify public access

3. Check Manifest:

   • Verify resource references
   • Check href attributes
   • Validate file paths

4. Test Direct Access:

   • Try accessing files directly
   • Check storage URLs
   • Verify file permissions

API Errors

Error: "Rate Limit Exceeded" (429)

Symptoms:

• 429 Too Many Requests
• Rate limit error message

Solutions:

1. Check Rate Limits:

   • Default: 100 requests/minute
   • Check your current usage
   • Monitor rate limit headers

2. Implement Backoff:

   async function makeRequestWithBackoff(url, options, retries = 3) {
     for (let i = 0; i < retries; i++) {
       const response = await fetch(url, options);
       
       if (response.status !== 429) {
         return response;
       }
       
       const retryAfter = parseInt(
         response.headers.get('Retry-After') || '60'
       );
       
       await new Promise(resolve => 
         setTimeout(resolve, retryAfter * 1000)
       );
     }
     
     throw new Error('Rate limit exceeded');
   }
   

3. Optimize Requests:

   • Batch requests when possible
   • Cache responses
   • Reduce polling frequency

4. Upgrade Plan:

   • Higher plans have higher limits
   • Contact support for custom limits
   • Consider enterprise plan

Error: "Internal Server Error" (500)

Symptoms:

• 500 Internal Server Error
• Generic error message

Solutions:

1. Retry Request:

   • Implement retry logic
   • Use exponential backoff
   • Retry up to 3 times

2. Check Request:

   • Verify request format
   • Check required fields
   • Validate data types

3. Check Status:

   • Verify API status
   • Check for maintenance
   • Review status page

4. Contact Support:

   • If error persists
   • Provide request details
   • Include error response

Performance Issues

Slow Package Processing

Symptoms:

• Processing takes >5 minutes
• Timeout errors

Solutions:

1. Optimize Package:

   • Reduce package size
   • Compress media files
   • Remove unnecessary files

2. Check Package Complexity:

   • Large packages take longer
   • Many files increase time
   • Complex manifests slow processing

3. Monitor Processing:

   • Use webhooks for status
   • Poll processing status
   • Set appropriate timeouts

Slow API Responses

Symptoms:

• API calls take >5 seconds
• Timeout errors

Solutions:

1. Optimize Queries:

   • Use pagination
   • Filter results
   • Limit response size

2. Cache Responses:

   • Cache package metadata
   • Cache session data
   • Use ETags when available

3. Check Network:

   • Verify network latency
   • Check geographic location
   • Use CDN if available

4. Reduce Requests:

   • Batch operations
   • Use webhooks instead of polling
   • Cache frequently accessed data

Getting Help

Before Contacting Support

1. Check Documentation:

   • Review relevant guides
   • Search documentation
   • Check examples

2. Review Error Details:

   • Read error messages carefully
   • Check error codes
   • Review response body

3. Test Isolation:

   • Test with minimal setup
   • Verify with test package
   • Check with different credentials

Contacting Support

When contacting support, provide:

1. Error Details:

   • Error message
   • Error code
   • HTTP status code

2. Request Information:

   • Endpoint called
   • Request method
   • Request body/parameters

3. Environment:

   • API version
   • Integration type
   • Package details (if relevant)

4. Steps to Reproduce:

   • Clear steps
   • Expected vs actual behavior
   • Screenshots if applicable

Related Documentation

• Package Errors - Package-specific issues
• Session Errors - Session-specific issues
• API Errors - API-specific issues
• Error Code Reference - Complete error codes

Last Updated: 2025-01-15