MindTickle Common Errors

Overview

MindTickle's API powers sales enablement workflows including course management, quiz administration, user provisioning via SCIM, and coaching analytics. Common integration errors include course access denied when user roles are misconfigured, quiz scoring discrepancies from version mismatches, and SCIM provisioning conflicts during bulk user imports from HR systems. The most frequent issue is 403 on course content access -- this almost always means the user is not enrolled, not that the API key lacks permissions. This reference covers authentication, content delivery, and user management errors that affect MindTickle platform integrations.

Error Reference

Error Handler

interface MindTickleError {
  code: number;
  message: string;
  category: "auth" | "rate_limit" | "validation" | "scim";
}

function classifyMindTickleError(status: number, body: string): MindTickleError {
  if (status === 401) {
    return { code: 401, message: body, category: "auth" };
  }
  if (status === 429) {
    return { code: 429, message: "Rate limited", category: "rate_limit" };
  }
  if (status === 409 && body.includes("SCIM")) {
    return { code: 409, message: body, category: "scim" };
  }
  return { code: status, message: body, category: "validation" };
}

Debugging Guide

Authentication Errors

MindTickle API keys are passed via Authorization: Bearer header. Keys are scoped to admin or read-only access levels. Most write operations require admin scope. Keys are automatically revoked when the issuing admin's account is deactivated -- re-issue from an active admin account.

Rate Limit Errors

The API enforces 60 requests/minute per key. User provisioning operations (SCIM) share the same limit as content APIs. Batch user creation using SCIM bulk endpoints instead of individual POST calls. Use Retry-After header and implement exponential backoff starting at 2 seconds. Analytics report generation is throttled more aggressively at 10 requests/minute.

Validation Errors

Course enrollment must precede content access -- a 403 on course content means the user is not enrolled, not that the API key is wrong. Quiz scoring errors occur when a quiz is updated after users have submitted attempts; re-publish the quiz and trigger re-grading. Module IDs differ between staging and production environments.

Error Handling

Quick Diagnostic

# Verify API connectivity and key validity
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $MINDTICKLE_API_KEY" \
  https://api.mindtickle.com/v2/users/me

Resources

• MindTickle Integration Docs
• MindTickle SCIM API Reference

Next Steps

See mindtickle-debug-bundle.