Error Codes

When something goes wrong, our API returns a meaningful error response. Here's what each code means and how to fix it.

Response Format

Error responses follow this structure:

{
  "status": 400,
  "success": "false",
  "message": "Human-readable description of what went wrong",
  "error": "ERROR_CODE"
}

HTTP Status Codes

400 Bad Request

Something's wrong with your request—missing fields, invalid data, or malformed JSON.

Common Causes:

Issue	Solution
Missing VF-ORG-ID header	Add the header to your request
Invalid JSON body	Check your JSON syntax
Missing required field	Include all required fields
roomId with invalid characters	Use only alphanumeric, hyphens, underscores
name too long	Keep names under 100 characters

Example:

{
  "status": 400,
  "success": false,
  "message": "Validation failed: participant.uid is required"
}

Debug Checklist:

1. Is your Content-Type header set to application/json?
2. Is your JSON valid? (No trailing commas, proper quoting)
3. Did you include all required fields?
4. Are field values within length/format constraints?

---

402 Payment Required

Your organization doesn't have enough credits to perform this action.

{
  "status": 402,
  "success": "false",
  "message": "Insufficient credits. Minimum 100 required to start a class."
}

Solution:

1. Log into your Verriflo Dashboard
2. Navigate to Billing/Credits
3. Top up your balance

Minimum Credits:

• Starting a new class requires at least 100 credits
• Credits are consumed based on participant-minutes

---

404 Not Found

The resource you're looking for doesn't exist.

Organization Not Found:

{
  "status": 404,
  "success": "false",
  "message": "Organization not found"
}

• Double-check your VF-ORG-ID value
• Make sure it matches exactly (case-sensitive)

Classroom Not Found:

{
  "status": 404,
  "success": "false",
  "message": "Classroom not found"
}

• Check the roomId spelling
• Room might belong to a different organization
• Room might not have been created yet

For Download Endpoints:

• Room might still be live (not ended yet)

---

409 Conflict

The request conflicts with the current state.

• Use a different roomId for new sessions
• Consider using unique IDs like math-101-2024-01-15

Recording In Progress:

{
  "status": 409,
  "success": "false",
  "message": "Recording is still being processed"
}

• Wait a few minutes for processing to complete
• Check back in 2-5 minutes

---

410 Gone

The resource existed but is no longer available.

Classroom Ended:

{
  "status": 410,
  "success": "false",
  "message": "This classroom has ended and cannot be rejoined"
}

• Once a teacher ends a class, that room is permanently closed
• Create a new room with a different roomId
• Consider using unique room IDs per session (e.g., math-101-2024-01-15)

Recording Expired:

{
  "status": 410,
  "success": "false",
  "message": "Recording download window has expired (6 hours)"
}

• Recordings are only available for 6 hours after class ends
• There's no way to recover expired recordings
• Set up automated downloads for future sessions

---

422 Unprocessable Entity

Your organization setup is incomplete. This is checked before creating or joining rooms.

Missing Name/Logo:

{
  "status": 422,
  "success": "false",
  "message": "Organization setup incomplete. Please configure organization name and logo.",
  "error": "ORG_SETUP_INCOMPLETE"
}

No Verified Domain:

{
  "status": 422,
  "success": "false",
  "message": "Organization must have at least one verified domain.",
  "error": "NO_VERIFIED_DOMAIN"
}

Required Setup Before Using API:

• Organization name
• Organization logo
• At least one verified domain

Solution:

1. Go to Dashboard → Organization Settings
2. Fill in all required fields
3. Add and verify at least one domain
4. Try your API call again

---

500 Internal Server Error

Something broke on our end.

{
  "status": 500,
  "success": "false",
  "message": "An unexpected error occurred"
}

What to Do:

1. Retry — Could be a temporary glitch
2. Wait — If it persists, we might be having issues
3. Contact Us — Email support@verriflo.com with:
   • Your request details (sanitized—no tokens)
   • Approximate timestamp
   • The error message you received

We monitor for 500s and usually know about issues quickly.

---

Error Handling Best Practices

1. Always Check the Status Code

const response = await fetch(url, options);
const data = await response.json();

if (!response.ok) {
  // Handle error based on status
  switch (response.status) {
    case 400:
      showValidationError(data.message);
      break;
    case 402:
      redirectToTopUp();
      break;
    case 404:
      if (isStudentJoin) {
        showWaitingScreen();
      } else {
        showNotFoundError();
      }
      break;
    case 409:
      showConflictError(data.message);
      break;
    case 410:
      showGoneError(data.message);
      break;
    default:
      showGenericError();
  }
  return;
}

// Handle success

2. Provide User-Friendly Messages

Don't show raw error messages to users. Translate them:

function getUserFriendlyMessage(status, apiMessage) {
  const messages = {
    402: "You've run out of credits. Please top up to continue.",
    404: "Class hasn't started yet. Please wait for your instructor.",
    410: "This class has ended. Please join the next session.",
    422: "Account setup incomplete. Please contact your administrator.",
  };

  return messages[status] || "Something went wrong. Please try again.";
}

3. Implement Retry Logic (for 500s)

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

      // Don't retry client errors
      if (response.status >= 400 && response.status < 500) {
        return response;
      }

      // Retry server errors
      if (response.status >= 500 && i < retries - 1) {
        await delay(1000 * (i + 1)); // Exponential backoff
        continue;
      }

      return response;
    } catch (networkError) {
      if (i === retries - 1) throw networkError;
      await delay(1000 * (i + 1));
    }
  }
}

---

Quick Reference Table

Code	When	User Message
400	Bad request data	"Please check your submission and try again"
402	Out of credits	"Credits needed. Please top up to continue."
404	Resource not found	"Not found" or "Waiting for class to start"
409	State conflict	"Action not allowed right now"
410	Resource gone	"This session has ended"
422	Setup incomplete	"Account setup needed"
500	Server error	"Something went wrong. Retrying..."

---

Need help? Reach out at support@verriflo.com.