MPP.Errors (mpp v0.6.0)

RFC 9457 Problem Details for MPP payment errors.

Each error type maps to a problem URI under https://paymentauth.org/problems/, an HTTP status code, and a human-readable title. Use to_map/1 to render an error as a JSON-compatible map for HTTP response bodies.

Problem Types

Charge / Core

:payment_required — no payment credential provided (402)
:payment_insufficient — payment amount too low (402)
:payment_expired — challenge has expired (402)
:verification_failed — payment proof is invalid (402)
:method_unsupported — payment method not accepted (400)
:malformed_credential — credential cannot be parsed (402)
:invalid_challenge — challenge ID doesn't match or is unknown (402)
:invalid_payload — credential payload doesn't match schema (402)
:bad_request — malformed request (400)
:payment_action_required — payment requires additional action, e.g. 3DS (402)

Session

:insufficient_balance — insufficient balance in the payment channel (402)
:invalid_signature — voucher or close request signature is invalid (402)
:signer_mismatch — recovered signer is not authorized for this channel (402)
:amount_exceeds_deposit — voucher cumulative amount exceeds the channel deposit (402)
:delta_too_small — voucher amount increase is below the minimum delta (402)
:channel_not_found — no channel with this ID exists (410)
:channel_closed — channel is closed or finalized (410)

API Functions

Function	Arity	Description	Param Kinds
`types`	0	Return the list of known problem type atoms.	-
`to_map`	1	Render the error as an RFC 9457 Problem Details map with string keys.	`error: value`
`to_json`	1	Render the error as an RFC 9457 Problem Details JSON string.	`error: value`
`new`	2	Create an RFC 9457 Problem Detail error for the given problem type.	`type: value`, `detail: value`

Summary

Types

problem_type()

t()

Functions

new(type, detail)

Create an RFC 9457 Problem Detail error for the given problem type.

to_json(error)

Render the error as an RFC 9457 Problem Details JSON string.

to_map(error)

Render the error as an RFC 9457 Problem Details map with string keys.

types()

Return the list of known problem type atoms.

Types

problem_type()

@type problem_type() ::
  :payment_required
  | :payment_insufficient
  | :payment_expired
  | :verification_failed
  | :method_unsupported
  | :malformed_credential
  | :invalid_challenge
  | :invalid_payload
  | :bad_request
  | :payment_action_required
  | :insufficient_balance
  | :invalid_signature
  | :signer_mismatch
  | :amount_exceeds_deposit
  | :delta_too_small
  | :channel_not_found
  | :channel_closed

t()

@type t() :: %MPP.Errors{
  detail: String.t(),
  status: pos_integer(),
  title: String.t(),
  type: String.t()
}

Functions

new(type, detail)

@spec new(problem_type(), String.t()) :: t()

Create an RFC 9457 Problem Detail error for the given problem type.

Parameters

type - Problem type atom (e.g., :payment_required, :verification_failed) (value)
detail - Human-readable error detail string (value)

Returns

Error struct with type URI, title, status, and detail (struct)

Composes With

to_map
to_json

# descripex:contract
%{
  params: %{
    type: %{
      description: "Problem type atom (e.g., `:payment_required`, `:verification_failed`)",
      kind: :value
    },
    detail: %{description: "Human-readable error detail string", kind: :value}
  },
  returns: %{
    type: :struct,
    description: "Error struct with `type` URI, `title`, `status`, and `detail`"
  },
  composes_with: [:to_map, :to_json]
}

to_json(error)

@spec to_json(t()) :: String.t()

Render the error as an RFC 9457 Problem Details JSON string.

Parameters

error - Error struct to serialize (value)

Returns

JSON string with type, title, status, detail keys (string)

Composes With

new
to_map

# descripex:contract
%{
  params: %{error: %{description: "Error struct to serialize", kind: :value}},
  returns: %{
    type: :string,
    description: "JSON string with `type`, `title`, `status`, `detail` keys"
  },
  composes_with: [:new, :to_map]
}

to_map(error)

@spec to_map(t()) :: map()

Render the error as an RFC 9457 Problem Details map with string keys.

Parameters

error - Error struct to render (value)

Returns

Map with "type", "title", "status", "detail" keys (map)

Composes With

new
to_json

# descripex:contract
%{
  params: %{error: %{description: "Error struct to render", kind: :value}},
  returns: %{
    type: :map,
    description: "Map with `\"type\"`, `\"title\"`, `\"status\"`, `\"detail\"` keys"
  },
  composes_with: [:new, :to_json]
}

types()

@spec types() :: [problem_type()]

Return the list of known problem type atoms.

# descripex:contract
%{}