Represents an error returned by the Humaans API or HTTP layer.

Error types

• :api_error - The API returned a non-2xx HTTP status code. The status field contains the HTTP status code and body contains the parsed response body. The Humaans API's structured error envelope (code, name, message, issues) is also extracted onto top-level fields when present.
• :network_error - A transport-level error occurred before a response was received (e.g. connection refused, DNS failure). The reason field contains the underlying error.

Structured API error fields

When the API returns a structured error body, the following fields are populated:

• code - Short error code, e.g. "ValidationError", "NotFound".
• name - Human-readable error name.
• api_message - The API's error message string. (Named to avoid shadowing the Exception.message/1 callback, which returns a formatted display string.)
• issues - List of field-level validation errors (each typically a map with path and message keys). nil if not present.

The raw body is always retained for forward-compatibility with undocumented fields.

Examples

case Humaans.People.retrieve(client, "missing-id") do
  {:ok, person} ->
    person

  {:error, %Humaans.Error{type: :api_error, status: 404}} ->
    :not_found

  {:error, %Humaans.Error{type: :api_error, status: 422, issues: issues}}
  when is_list(issues) ->
    {:invalid, issues}

  {:error, %Humaans.Error{type: :api_error, status: 401}} ->
    :unauthorized

  {:error, %Humaans.Error{type: :network_error, reason: reason}} ->
    {:network_failure, reason}
end