Skip to main content

​
Overview

The Ilumiera AI B2B API uses standard HTTP status codes and provides error messages to help you understand and resolve issues. All error responses follow a consistent structure.

​
HTTP Status Codes

​
Success Codes

  • 200 OK: Request completed successfully
  • 201 Created: Resource created successfully (e.g., organization creation)

​
Client Error Codes

  • 400 Bad Request: Invalid request parameters or malformed data
  • 401 Unauthorized: Missing or invalid authentication credentials
  • 403 Forbidden: Valid credentials but insufficient permissions
  • 404 Not Found: Requested resource not found
  • 429 Too Many Requests: Rate limit exceeded (if implemented)

​
Server Error Codes

  • 500 Internal Server Error: Unexpected server error
  • 502 Bad Gateway: Upstream service unavailable
  • 503 Service Unavailable: Service temporarily unavailable
  • 504 Gateway Timeout: Request timeout

​
Error Response Format

Error responses typically include an error message: 
{
  "error": "Error description"
}
Some endpoints may return plain text error messages: 
Not found

​
Common Error Scenarios

​
Authentication Errors

​
Missing Firebase Token

{
  "error": "Unauthorized access"
}

​
Invalid API Key

{
  "error": "Invalid API key"
}

​
Missing API Key

{
  "error": "API key is required"
}

​
Organization Errors

​
Organization Not Found

{
  "error": "Organisation not found"
}

​
API Key Not Found

API key not found

​
Source Processing Errors

​
Invalid Source ID

Source not found

​
Unauthorized Source Access

{
  "error": "Not authorized to access this source"
}

​
Processing Failed

{
  "error": "Failed to process source content"
}

​
Content Generation Errors

​
Quiz Generation Failed

{
  "error": "Failed to generate quiz"
}

​
Flashcard Generation Failed

{
  "error": "Failed to generate flashcards"
}

​
Mind Map Generation Failed

{
  "error": "Failed to generate mind map"
}

​
Resource Not Found

​
Quiz Not Found

Quiz not found

​
Flashcard Not Found

Flashcard not found

​
Mind Map Not Found

Mindmap not found

​
Error Handling Best Practices

​
1. Check Response Status

const response = await fetch(
  "https://b2b-api-backend-95487.ondigitalocean.app/source/generateQuiz/sourceId",
  {
    method: "POST",
    headers: {
      "api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ userId: "user-123" }),
  }
);

if (!response.ok) {
  const errorText = await response.text();

  try {
    const errorJson = JSON.parse(errorText);
    console.error("API Error:", errorJson.error);
  } catch {
    console.error("API Error:", errorText);
  }

  // Handle specific status codes
  switch (response.status) {
    case 401:
      // Handle authentication error
      break;
    case 404:
      // Handle not found error
      break;
    case 500:
      // Handle server error
      break;
  }
}

​
2. Implement Retry Logic

For transient errors (5xx status codes), implement exponential backoff: 
async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.ok) {
        return response;
      }

      // Don't retry client errors (4xx)
      if (response.status >= 400 && response.status < 500) {
        throw new Error(`Client error: ${response.status}`);
      }

      // Retry on server errors (5xx)
      if (attempt === maxRetries - 1) {
        throw new Error(`Server error after ${maxRetries} attempts`);
      }

      // Exponential backoff
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise((resolve) => setTimeout(resolve, delay));
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
    }
  }
}

​
3. Handle File Upload Errors

When uploading files, handle specific error cases: 
const formData = new FormData();
formData.append("file", pdfFile);
formData.append(
  "source",
  JSON.stringify({
    sourceType: "file",
    userId: "user-123",
  })
);

try {
  const response = await fetch(
    "https://b2b-api-backend-95487.ondigitalocean.app/source/ingestSource",
    {
      method: "POST",
      headers: {
        "api-key": "YOUR_API_KEY",
      },
      body: formData,
    }
  );

  if (!response.ok) {
    if (response.status === 400) {
      console.error("Invalid file format or missing parameters");
    } else if (response.status === 413) {
      console.error("File too large");
    }
  }
} catch (error) {
  console.error("Network error:", error);
}

​
4. User-Friendly Error Messages

Map API errors to user-friendly messages: 
function getUserFriendlyMessage(status, error) {
  switch (status) {
    case 401:
      return "Authentication failed. Please check your API key.";
    case 404:
      return "The requested resource was not found.";
    case 400:
      return "Invalid request. Please check your input.";
    case 500:
      return "Server error. Please try again later.";
    default:
      return error || "An unexpected error occurred.";
  }
}

​
Debugging Tips

​
1. Log Full Response Details

if (!response.ok) {
  console.error({
    status: response.status,
    statusText: response.statusText,
    headers: Object.fromEntries(response.headers.entries()),
    url: response.url,
    timestamp: new Date().toISOString(),
  });
}

​
2. Check CORS Headers

If experiencing CORS issues in the browser: 
// CORS is enabled for all origins during beta
// But ensure you're not sending credentials unnecessarily
const response = await fetch(url, {
  method: "POST",
  headers: {
    "api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  // Don't include credentials unless needed
  credentials: "omit",
});

​
3. Validate Request Format

Always validate your request format before sending: 
// For JSON requests
const validateJsonRequest = (data) => {
  try {
    JSON.stringify(data);
    return true;
  } catch {
    console.error("Invalid JSON in request body");
    return false;
  }
};

// For file uploads
const validateFileUpload = (file) => {
  const maxSize = 50 * 1024 * 1024; // 50MB
  const allowedTypes = ["application/pdf"];

  if (file.size > maxSize) {
    console.error("File too large");
    return false;
  }

  if (!allowedTypes.includes(file.type)) {
    console.error("Invalid file type");
    return false;
  }

  return true;
};

​
Getting Help

If you encounter persistent errors:
  1. Double-check your authentication: Ensure you’re using the correct authentication method for each endpoint
  2. Verify endpoint URLs: Make sure you’re using the correct base URL and path
  3. Check request format: Ensure your request body matches the expected format
  4. Contact support: Email [email protected] with error details and timestamps