# `OzMcp.Utils.Error`
[🔗](https://github.com/oz-elixir/oz_mcp/blob/v0.9.0/lib/oz_mcp/utils/error.ex#L1)

A JSON-RPC error that a callback returns.

The struct has three fields: `code` (an integer), `message` (a
string) and `data` (a map or a list, or `nil`). The framework puts
the fields in the `error` object of the JSON-RPC response. The client
receives the `code`, the `message` and the `data` as they are.

## When to return an error struct

Return `{:error, %OzMcp.Utils.Error{}}` for a protocol error: the
entity does not exist, or the request does not agree with the
protocol. The framework answers an unknown entity itself.

| Helper | Code | Use |
|---|---|---|
| `invalid_params/2` | `-32602` | an invalid argument |
| `resource_not_found/1` | `-32002` | a resource uri whose data does not exist |
| `internal_error/2` | `-32603` | a failure of the callback that has no better code |
| `new/3` | any | another code |

A tool callback that returns the error struct sends the failure as a
JSON-RPC error: the model does not read it. A task-augmented call
that gets an error struct makes the task `failed`.

## When to return a tool error result

In a tool callback, return `{:ok, result}` with `isError: true` when
the work of the tool failed and the model can correct the input. The
model reads the `content` of the result:

    {:ok,
     %CallToolResult{}
     |> CallToolResult.content([
       %TextContent{} |> TextContent.text("The city is unknown")
     ])
     |> CallToolResult.is_error(true)
     |> CallToolResult.build()}

The `read/2`, `read/4` and `get/2` callbacks have no tool error
result: they return the error struct for each failure.

# `t`

```elixir
@type t() :: %OzMcp.Utils.Error{
  code: integer(),
  data: map() | list() | nil,
  message: String.t()
}
```

# `internal_error`

```elixir
@spec internal_error(String.t(), map() | list() | nil) :: %OzMcp.Utils.Error{
  code: term(),
  data: term(),
  message: term()
}
```

Builds the error `-32603`. The client reads the `message`: keep the details out.

# `invalid_params`

```elixir
@spec invalid_params(String.t(), map() | list() | nil) :: %OzMcp.Utils.Error{
  code: term(),
  data: term(),
  message: term()
}
```

Builds the error `-32602`: the `message` names the invalid argument.

# `new`

```elixir
@spec new(integer(), String.t(), map() | list() | nil) :: %OzMcp.Utils.Error{
  code: term(),
  data: term(),
  message: term()
}
```

Builds an error struct with a `code`, a `message` and an optional
`data`. The `data` is a map or a list of JSON terms, or `nil`.

# `resource_not_found`

```elixir
@spec resource_not_found(String.t()) :: %OzMcp.Utils.Error{
  code: term(),
  data: term(),
  message: term()
}
```

Builds the error `-32002` with the data `%{"uri" => uri}`.

---

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