Possible issues during communication

This section assumes you've correctly set up a message listener to receive events from the Classwise app.

See: Receiving messages from Classwise

Whenever an issue occurs, Classwise will send a message containing an error object that describes what went wrong.

Invalid JSON

You can send raw JavaScript objects to Classwise — no need to stringify them manually.

However, if you choose to send the payload as a string, and it is not a valid JSON, Classwise will respond with an error indicating that parsing failed.

{
  "error": { "message": "invalid_json_format" }
}

Message validation failed

If the received JSON object is correctly formatted but missing required fields or contains invalid values, you will receive a Message validation failed error from Classwise. This error will include a details object with three representations of the validation errors. All of them are generated using the Zod validation library:

• issues - an array describing which fields are missing or invalid. See: https://zod.dev/error-formatting
• prettified - a human-readable string summarizing the validation errors. See: https://zod.dev/error-formatting?id=zprettifyerror
• treeified - a nested tree-like structure of errors that mirrors data schema. See: https://zod.dev/error-formatting?id=ztreeifyerror

Example JSON:

{
  "error": {
    "message": "Message validation failed",
    "details": {
      "issues": [
        {
          "expected": "string",
          "code": "invalid_type",
          "path": ["data", "quiz", "title"],
          "message": "Invalid input: expected string, received undefined"
        },
        {
          "code": "invalid_union",
          "errors": [],
          "note": "No matching discriminator",
          "path": ["data", "quiz", "questions", 0, "type"],
          "message": "Invalid input"
        }
      ],
      "prettified": "✖ Invalid input: expected string, received undefined\n  → at data.quiz.title\n✖ Invalid input\n  → at data.quiz.questions[0].type",
      "treeified": {
        "errors": [],
        "properties": {
          "data": {
            "errors": [],
            "properties": {
              "quiz": {
                "errors": [],
                "properties": {
                  "title": {
                    "errors": [
                      "Invalid input: expected string, received undefined"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Sign-In or Account Linking Errors

There are two scenarios in which Classwise sends a token to our server for validation:

1. Sign-in with JWT – triggered after sending a mode_selection message.
2. Account linking – triggered when the user agrees to link their external account to a Classwise account.

In both cases, the server will verify the token and if error occurs, it will send details about that to you and send another waiting_for_mode_selection message, asking to resend mode selection for another attempt.

{
  "error": {
    "message": "sign_in_with_partner_token_error" or "link_account_error",
    "details": "<error_code_or_message>"
  }
}

Possible error codes:

Below is a list of possible error codes returned during token validation, along with explanations:

• partner_not_found Classwise does not recognize the requesting partner. Please contact support to verify your integration details.
• token_expired The JWT token has expired — the exp (expiration) timestamp is in the past. Generate and resend a valid token.
• token_not_yet_valid The JWT token is not yet valid — the iat (issued at) timestamp is set in the future. Ensure your server clock is accurate and resend the token.
• invalid_token The token is structurally valid but contains invalid claims or data. This may include missing fields, incorrect formats, or unauthorized access.
• token_decoding_failed Classwise was unable to decode or verify the JWT token. Please ensure it is properly signed and formatted. Contact support if the issue persists.

Message sent is invalid for current Classwise App stage

If Classwise is expecting a token payload or quiz content, but receives a message that doesn't match the current stage of the flow, it will respond with an unexpected_message_type error.

Make sure you're sending messages that align with the expected communication step (e.g., don’t send quiz data before authentication is complete).

{
  "error": {
    "message": "unexpected_message_type",
    "details": "Current flow stage is waiting_for_token, but received message of type start_quiz"
  }
}