Error Handling

When a launch fails, you need to know what went wrong and how to respond. Ltix returns {:error, exception} from both handle_login/3 and handle_callback/3, with errors organized into three classes using Splode. You can match on the category without knowing every individual error type.

Error classes

Matching on class

Every Ltix error struct has a class field you can match on:

case Ltix.handle_callback(params, state) do
  {:ok, context} ->
    handle_launch(conn, context)

  {:error, error} ->
    case error.class do
      :invalid ->
        conn |> put_status(400) |> text("Bad request: #{Exception.message(error)}")

      :security ->
        conn |> put_status(401) |> text("Unauthorized: #{Exception.message(error)}")

      :unknown ->
        Logger.error("LTI launch failed: #{Exception.message(error)}")
        conn |> put_status(500) |> text("Internal error")
    end
end

Matching on specific errors

For finer control, match on the error struct directly:

case Ltix.handle_login(params, launch_url) do
  {:ok, result} ->
    # ...

  {:error, %Ltix.Errors.Invalid.RegistrationNotFound{issuer: issuer}} ->
    Logger.warning("Unknown platform attempted login: #{issuer}")
    conn |> put_status(404) |> text("Platform not registered")

  {:error, %Ltix.Errors.Invalid.MissingParameter{parameter: param}} ->
    conn |> put_status(400) |> text("Missing required parameter: #{param}")

  {:error, error} ->
    conn |> put_status(400) |> text(Exception.message(error))
end

Error messages and spec references

Every error produces a human-readable message via Exception.message/1 and most carry a spec_ref field pointing to the violated spec section:

error = %Ltix.Errors.Security.TokenExpired{spec_ref: "Sec §5.1.3 step 5"}

Exception.message(error)
#=> "JWT token has expired [Sec §5.1.3 step 5]"

error.spec_ref
#=> "Sec §5.1.3 step 5"

The spec reference is useful for debugging — it tells you exactly which validation step failed.

Invalid errors

These indicate problems with the incoming data:

Security errors

These indicate the launch failed a security check:

Advantage service errors

These errors apply to LTI Advantage service calls (memberships, AGS, etc.) and OAuth authentication.

Invalid

Security

Logging recommendations

Invalid errors are usually the platform's fault (misconfiguration, bad requests). Security errors could be attacks or clock skew. Unknown errors need investigation:

{:error, error} ->
  case error.class do
    :invalid ->
      Logger.info("LTI invalid request: #{Exception.message(error)}")

    :security ->
      Logger.warning("LTI security violation: #{Exception.message(error)}")

    :unknown ->
      Logger.error("LTI unexpected error: #{Exception.message(error)}")
  end