nhttp_error (nhttp_lib v1.0.0)
View SourceUnified error handling for nhttp HTTP library.
Provides a consistent error taxonomy across client and server components.
All errors use the format {error, {Category, Reason}} where Category
identifies the error domain and Reason provides specific details.
Error Categories
connection- Connection establishment failuresrequest- Request/response cycle failureshttp2- HTTP/2 protocol-specific errorspool- Connection pool errorsserver- Server-side acceptor / listener / handler failures
Usage
case connect(Host, Port) of
{ok, Conn} -> {ok, Conn};
{error, econnrefused} -> nhttp_error:connect_refused(econnrefused);
{error, timeout} -> nhttp_error:connect_timeout()
end.
case nhttpc:get(Url) of
{ok, Resp} -> handle_response(Resp);
{error, {connection, _}} -> retry_with_backoff();
{error, {request, {timeout, _}}} -> return_504();
{error, {pool, checkout_timeout}} -> return_503()
end.
case nhttp_error:is_retryable(Error) of
true -> retry_request();
false -> return_error()
end.Summary
Functions
Accept socket was closed.
File descriptor limit reached during accept (retryable).
Accept timed out waiting for a new connection.
ALPN protocol negotiation failed.
Server is at connection capacity.
Body receive timed out after the specified duration.
Get the category of an error.
Timed out waiting for a connection from the pool.
Connection attempt failed with the given POSIX error.
Connection is not ready for use.
Connection was refused by the remote host.
Connection attempt timed out.
Connection attempt timed out after the specified duration.
Connection was closed during request processing.
Connection was closed with a retryable or unexpected tag.
Connection is in the process of closing.
File operation failed during request processing.
File operation failed for the given path.
Send blocked by HTTP/2 flow control window.
HTTP/2 flow control error.
Format error for logging.
Received GOAWAY frame with the given error code.
Received GOAWAY frame, marked as retryable.
HTTP/2 connection-level error.
HTTP/2 protocol error.
Handler init callback failed.
Check if error is retryable (connection-level or transient). Retryable errors are those where a fresh connection or retry might succeed.
Check if error is transient (may succeed on immediate retry). Transient errors are a subset of retryable errors where the issue is likely temporary (e.g., connection reset vs. server down).
Listen socket could not be opened.
Received a malformed response that could not be parsed.
Maximum number of redirects exceeded.
Required configuration key is missing.
No connections available in the pool.
Normalize raw errors into structured t() tuples. Converts various error formats from sockets, TLS, and protocol layers into a consistent categorized format.
Connection pool is draining and not accepting new requests.
Connection pool is exhausted.
Protocol-level error on a server connection.
HTTP/2 rate limiting applied by the peer.
Error receiving data from the socket.
Redirect loop detected at the given URL.
Request timed out.
Request timed out after the specified duration.
Response body exceeded the maximum allowed size.
Error sending data on the socket.
Server socket error.
Server-side stream was closed.
HTTP/2 stream was cancelled.
HTTP/2 stream was closed.
HTTP/2 stream was refused by the peer (retryable).
HTTP/2 stream was reset with the given error code.
Response stream was stopped by the caller.
Response stream was stopped with accumulated partial data.
TLS handshake or protocol error.
Upload processing failed.
WebSocket protocol error.
WebSocket upgrade handshake failed.
Types
Functions
-spec accept_closed() -> t().
Accept socket was closed.
-spec accept_emfile() -> t().
File descriptor limit reached during accept (retryable).
-spec accept_timeout() -> t().
Accept timed out waiting for a new connection.
ALPN protocol negotiation failed.
-spec at_capacity() -> t().
Server is at connection capacity.
Body receive timed out after the specified duration.
Get the category of an error.
-spec checkout_timeout() -> t().
Timed out waiting for a connection from the pool.
-spec connect_failed(inet:posix()) -> t().
Connection attempt failed with the given POSIX error.
-spec connect_not_ready() -> t().
Connection is not ready for use.
-spec connect_refused(inet:posix()) -> t().
Connection was refused by the remote host.
-spec connect_timeout() -> t().
Connection attempt timed out.
Connection attempt timed out after the specified duration.
-spec connection_closed() -> t().
Connection was closed during request processing.
-spec connection_closed(retryable | unexpected) -> t().
Connection was closed with a retryable or unexpected tag.
-spec connection_closing() -> t().
Connection is in the process of closing.
File operation failed during request processing.
-spec file_error(atom(), file:filename(), term()) -> t().
File operation failed for the given path.
-spec flow_control_blocked(integer(), pos_integer()) -> t().
Send blocked by HTTP/2 flow control window.
HTTP/2 flow control error.
Format error for logging.
-spec goaway(nhttp_h2:error_code()) -> t().
Received GOAWAY frame with the given error code.
-spec goaway(nhttp_h2:error_code(), retryable) -> t().
Received GOAWAY frame, marked as retryable.
HTTP/2 connection-level error.
HTTP/2 protocol error.
Handler init callback failed.
Check if error is retryable (connection-level or transient). Retryable errors are those where a fresh connection or retry might succeed.
Check if error is transient (may succeed on immediate retry). Transient errors are a subset of retryable errors where the issue is likely temporary (e.g., connection reset vs. server down).
-spec listen_failed(inet:posix()) -> t().
Listen socket could not be opened.
Received a malformed response that could not be parsed.
-spec max_redirects(non_neg_integer()) -> t().
Maximum number of redirects exceeded.
Required configuration key is missing.
-spec no_connections() -> t().
No connections available in the pool.
Normalize raw errors into structured t() tuples. Converts various error formats from sockets, TLS, and protocol layers into a consistent categorized format.
-spec pool_draining() -> t().
Connection pool is draining and not accepting new requests.
Connection pool is exhausted.
Protocol-level error on a server connection.
-spec rate_limited() -> t().
HTTP/2 rate limiting applied by the peer.
-spec recv_error(inet:posix()) -> t().
Error receiving data from the socket.
Redirect loop detected at the given URL.
-spec request_timeout() -> t().
Request timed out.
Request timed out after the specified duration.
-spec response_too_large(non_neg_integer(), non_neg_integer()) -> t().
Response body exceeded the maximum allowed size.
-spec send_error(inet:posix()) -> t().
Error sending data on the socket.
-spec server_socket_error(inet:posix()) -> t().
Server socket error.
-spec server_stream_closed(non_neg_integer()) -> t().
Server-side stream was closed.
-spec stream_cancelled() -> t().
HTTP/2 stream was cancelled.
HTTP/2 stream was closed.
-spec stream_refused() -> t().
HTTP/2 stream was refused by the peer (retryable).
-spec stream_reset(nhttp_h2:error_code()) -> t().
HTTP/2 stream was reset with the given error code.
Response stream was stopped by the caller.
Response stream was stopped with accumulated partial data.
TLS handshake or protocol error.
Upload processing failed.
WebSocket protocol error.
WebSocket upgrade handshake failed.