# `JoobQ.Error`
[🔗](https://github.com/azutoolkit/joobqui/tree/master/sdks/elixir/blob/main/lib/joobq/error.ex#L2)

A gateway call that did not succeed: the gateway answered an error status, or it could not be reached.

`reason` is the kind of failure to match on: `:pro_required` (402, the call needs a JoobQ Pro licence),
`:unauthorized` (401, a wrong SDK token), `:invalid` (422, the gateway refused the request; also a body Jason cannot
encode, never sent: `status` is nil), `:unavailable` (5xx), `:transport` (no answer: `status` is nil),
`:bad_response` (a 2xx answer that is not JSON) or `:gateway` (any other status). `code`, `message`, `details` and
`request_id` are the gateway's error envelope; `message` is cut to 300 characters.

`jq_code` is the error's registry code (`"JQ-801"`) when an answer of 400 or more carries one (`JQ-` and 3 or 4
digits; anything else is ignored), nil otherwise, and `docs_url` where it is documented, built by the SDK
(`https://joobq.io/errors/<jq_code>`), never taken from the answer. With a `jq_code`, `Exception.message/1` gives the
gateway's message cleaned to one line and ends with ` [<jq_code>] <docs_url>`.

A 426 (the gateway refuses this SDK's version) is a `JoobQ.SdkTooOldError` instead, with the same fields and the
reason `:sdk_too_old`: match on `{:error, %{reason: reason}}` to handle both.

A producer call that answers `:transport` or `:bad_response` MAY have stored the job: the gateway can have stored it
before the connection broke. A retry is safe only with a `unique_key` (`JoobQ.Job`).

# `reason`

```elixir
@type reason() ::
  :pro_required
  | :unauthorized
  | :invalid
  | :unavailable
  | :transport
  | :bad_response
  | :gateway
```

# `t`

```elixir
@type t() :: %JoobQ.Error{
  __exception__: true,
  code: String.t(),
  details: term(),
  docs_url: String.t() | nil,
  jq_code: String.t() | nil,
  message: String.t(),
  reason: reason(),
  request_id: String.t() | nil,
  status: pos_integer() | nil
}
```

# `bad_response`

```elixir
@spec bad_response(pos_integer()) :: t()
```

The error for a 2xx answer with status `status` whose body is not JSON.

# `from_response`

```elixir
@spec from_response(pos_integer(), term()) :: t()
```

The error for an answer with status `status` and its body (decoded JSON, or the raw text).

# `transport`

```elixir
@spec transport(Exception.t() | term()) :: t()
```

The error for a call the gateway never answered (`exception` is the HTTP client's).

# `unencodable`

```elixir
@spec unencodable() :: t()
```

The error for a request body Jason cannot encode (a tuple, a pid, ...): nothing was sent.

---

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