Error reference

Stable, machine-readable errors

Every error is JSON with a stable error code. Match on the code, not the message. Denied requests are never counted against quota.

401

api_key_required

WhenNo Authorization: Bearer header on a protected endpoint.

FixSend Authorization: Bearer YOUR_API_KEY on every protected request.

Response body · JSON

{
  "ok": false,
  "error": "api_key_required",
  "message": "A valid MMSx / MoPro API key is required for this endpoint."
}

401

invalid_api_key

WhenThe presented key does not exist or is malformed.

FixCheck for whitespace or truncation; keys start with mmsx_beta_.

Response body · JSON

{
  "ok": false,
  "error": "invalid_api_key",
  "message": "The supplied API key is not valid."
}

401

expired_api_key

WhenThe key passed its expires_at timestamp.

FixRequest a fresh key; expiry is set at creation for time-boxed access.

Response body · JSON

{
  "ok": false,
  "error": "expired_api_key",
  "message": "This API key has expired."
}

401

revoked_api_key

WhenThe key was revoked by its owner or an administrator.

FixRevocation is permanent; request a replacement key.

Response body · JSON

{
  "ok": false,
  "error": "revoked_api_key",
  "message": "This API key has been revoked."
}

403

blocked_api_key

WhenThe key was administratively blocked (abuse or policy).

FixContact TrainersEye / MoPro support to review the block.

Response body · JSON

{
  "ok": false,
  "error": "blocked_api_key",
  "message": "This API key has been blocked."
}

429

quota_exceeded

WhenThe plan's monthly request quota is used up.

FixWait for the monthly reset, or upgrade the plan. Denied requests are not counted against quota.

Response body · JSON

{
  "ok": false,
  "error": "quota_exceeded",
  "plan": "Developer",
  "monthly_limit": 10000,
  "used": 10000,
  "message": "Monthly API request quota exceeded."
}

403

endpoint_not_allowed_for_plan

WhenThe plan does not include this endpoint (e.g. Free Sandbox calling /v3/exercise/tree).

FixSee the plan matrix on the pricing page; upgrade for full access.

Response body · JSON

{
  "ok": false,
  "error": "endpoint_not_allowed_for_plan",
  "message": "This endpoint is not included in the current plan."
}

404

not_found

WhenNo ontology node matches the requested name.

FixResolve names through /v3/exercise/search first, then call profile/tree with the canonical name.

Response body · JSON

{
  "ok": false,
  "error": "not_found",
  "message": "No exercise matched the requested name."
}

200

low_confidence_match

WhenSearch resolved a term but below the confidence threshold.

FixInspect the confidence field on results and confirm ambiguous matches with the user before acting on them.

Response body · JSON

{
  "ok": true,
  "resolved": false,
  "confidence": 0.41,
  "message": "Low-confidence match; confirm before use."
}

422

validation_error

WhenA required query parameter is missing or malformed.

FixCheck the parameter table in the API reference (q, name, limit).

Response body · JSON

{
  "ok": false,
  "error": "validation_error",
  "message": "Query parameter 'name' is required."
}

500

internal_error

WhenAn unexpected server-side failure.

FixRetry with backoff; if persistent, report it with the request path and timestamp.

Response body · JSON

{
  "ok": false,
  "error": "internal_error",
  "message": "Unexpected server error."
}