thinwrap_location_error (thinwrap_location v1.3.0)

Builders for thinwrap_location:connector_error/0, the plain map every operation failure is returned as.

Connectors build errors here and fail/1 them; the public thinwrap_location functions catch that and return {error, Error}. Misuse of the API (a missing config key, a bad enum atom) is not a connector error: it raises badarg.

There is deliberately no retry_after_seconds key: the raw Retry-After header rides in cause as <<"retryAfter">>, and its parsed seconds are woven into provider_message.

Summary

Types

code()

Functions

classified(Code, Status, Cause, Msg0)

An error with an explicit code for an in-body vendor error (a 2xx with an error payload): message and cause are credential-redacted, the cause keeping its shape.

codes()

Every code() value, in declaration order.

fail(Error)

Abort the current operation with Error. Only valid inside a call made through thinwrap_location, which turns it into {error, Error}.

invalid_request(Msg)

A pre-flight invalid_request (no HTTP round-trip).

new(Code, Fields)

Build an error. Fields may carry status, provider_message, message and cause; message falls back to provider_message, then to a generic text, so it is always present.

provider_error(Status, Headers, Body, Code, ProviderMsg)

The error for a non-2xx response. The status-to-code classification and the message are the connector's; this adds the shared Retry-After surfacing: the raw header is merged into the decoded body as <<"retryAfter">> and its parsed seconds appended to the message.

require_list(Status, Raw, Key, Label)

require_list/5 with MissingOk = false.

require_list(Status, Raw, Key, Label, MissingOk)

The list under Raw[Key] of a 2xx body, or fail/1 with unknown.

unknown(Status, Cause, Msg)

An unknown error for a malformed vendor body.

unsupported_option(Msg)

A pre-flight unsupported_option (no HTTP round-trip).

Types

code()

-type code() ::
          invalid_recipient | rate_limited | auth_failed | provider_unavailable | invalid_request |
          unknown | unsupported_field | unsupported_option | unsupported_travel_mode |
          profile_not_configured | matrix_polling_timeout | no_route | timeout.

Functions

classified(Code, Status, Cause, Msg0)

-spec classified(code(), integer() | undefined, term(), binary()) -> thinwrap_location:connector_error().

An error with an explicit code for an in-body vendor error (a 2xx with an error payload): message and cause are credential-redacted, the cause keeping its shape.

codes()

-spec codes() -> [code()].

Every code() value, in declaration order.

fail(Error)

-spec fail(thinwrap_location:connector_error()) -> no_return().

Abort the current operation with Error. Only valid inside a call made through thinwrap_location, which turns it into {error, Error}.

invalid_request(Msg)

-spec invalid_request(binary()) -> thinwrap_location:connector_error().

A pre-flight invalid_request (no HTTP round-trip).

new(Code, Fields)

-spec new(code(), map()) -> thinwrap_location:connector_error().

Build an error. Fields may carry status, provider_message, message and cause; message falls back to provider_message, then to a generic text, so it is always present.

provider_error(Status, Headers, Body, Code, ProviderMsg)

-spec provider_error(integer(),
                     thinwrap_location_transport:headers(),
                     term(),
                     code(),
                     binary() | undefined) ->
                        thinwrap_location:connector_error().

The error for a non-2xx response. The status-to-code classification and the message are the connector's; this adds the shared Retry-After surfacing: the raw header is merged into the decoded body as <<"retryAfter">> and its parsed seconds appended to the message.

require_list(Status, Raw, Key, Label)

-spec require_list(integer(), term(), binary(), binary()) -> list().

require_list/5 with MissingOk = false.

require_list(Status, Raw, Key, Label, MissingOk)

-spec require_list(integer(), term(), binary(), binary(), boolean()) -> list().

The list under Raw[Key] of a 2xx body, or fail/1 with unknown.

A body that is not a JSON object, or whose result list is absent or not a list, is a response the connector cannot interpret: returning an empty result for it would present an outage or a truncated body as a genuine "no results". MissingOk is for vendors whose JSON drops an empty list entirely (Google's proto3 JSON omits empty repeated fields), where absence IS the zero answer.

unknown(Status, Cause, Msg)

-spec unknown(integer() | undefined, term(), binary()) -> thinwrap_location:connector_error().

An unknown error for a malformed vendor body.

unsupported_option(Msg)

-spec unsupported_option(binary()) -> thinwrap_location:connector_error().

A pre-flight unsupported_option (no HTTP round-trip).