# `MPP.Errors`
[🔗](https://github.com/ZenHive/mpp/blob/v0.10.0/lib/mpp/errors.ex#L1)

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)
  * `:credential_mismatch` — echoed challenge fields don't match this endpoint (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` |

# `problem_type`

```elixir
@type problem_type() ::
  :payment_required
  | :payment_insufficient
  | :payment_expired
  | :verification_failed
  | :method_unsupported
  | :malformed_credential
  | :invalid_challenge
  | :credential_mismatch
  | :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`

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

# `new`

```elixir
@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`

```elixir
# 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`

```elixir
@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`

```elixir
# 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`

```elixir
@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`

```elixir
# 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`

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

Return the list of known problem type atoms.

```elixir
# descripex:contract
%{}
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*