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

HTTP status codes

Every error has an HTTP status code derived from its class.

Use Ltix.Errors.status_code/1 to get it.

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

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

Plug.Exception

If your application depends on Plug, Ltix errors automatically implement the Plug.Exception protocol. Phoenix error views and Plug.Debugger use the correct status code without any extra work on your part.

Matching on class

Every Ltix error struct has a class field you can match on for different handling per category.

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

  {:error, error} ->
    status = Ltix.Errors.status_code(error)

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

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

      :unknown ->
        Logger.error("LTI launch failed: #{Exception.message(error)}")
        conn |> put_status(status) |> 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

Single and grouped errors

A single failure returns its error struct directly. When validation finds several problems at once, such as two malformed claims, they are grouped in their class struct and errors lists each one.

case Ltix.LaunchClaims.from_json(claims) do
  {:ok, claims} ->
    claims

  {:error, %Ltix.Errors.Invalid{errors: errors}} ->
    Enum.each(errors, &Logger.warning(Exception.message(&1)))

  {:error, error} ->
    Logger.warning(Exception.message(error))
end

The message of a grouped error lists the message of each error it contains.

Invalid options

Ltix raises Ltix.Errors.Invalid.InvalidOption when a function gets an unknown option, a missing required option, or an option with a value of the wrong type.

Ltix.JWK.generate(key_sise: 4096)
** (Ltix.Errors.Invalid.InvalidOption) Option :key_sise is unknown

Error messages and spec references

Every error produces a human-readable message via Exception.message/1 and most have a spec_ref field with the violated spec section.

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

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

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

The spec reference is useful for debugging because it identifies exactly which validation step failed.

Invalid errors

These indicate problems with the incoming data or the calling code.

Security errors

These indicate the launch failed a security check.

Unknown errors

These indicate an unexpected failure outside the incoming request.

Deep linking errors

These errors come from Ltix.DeepLinking.build_response/3. Content item constructors such as Ltix.DeepLinking.ContentItem.Link.new/1 return InvalidField. Errors about one item in a response include its index in the list you passed.

Advantage service errors

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

Invalid

Security

Unknown

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