package awskit

  1. Overview
  2. Docs

Module Awskit.ErrorSource

Structured core error type.

Structured core AWS SDK errors.

Service packages preserve this value and add classifier helpers over it. Errors carry a structured kind plus an outer context stack. Human output is optimized for logs and CLI diagnostics; sexp output is optimized for structured debugging.

Application code should treat this module as a consumer API: inspect, classify, and print errors returned by Awskit operations.

The Producer submodule is the producer-side API for custom runtime authors, awskit service packages, runtime adapters, simulators, and tests that need to construct the shared opaque error type. It is not part of the application-facing consumer contract.

Sourcetype t

Opaque structured error. Use the accessors below for classification and diagnostics; use Producer only at implementation boundaries.

Sourceexception Awskit_error of t

Raised by explicit _exn helpers. Non-exception APIs return t in their Error case.

Sourcetype validation = private {
  1. field : string option;
  2. message : string;
}

Caller/input validation error.

Sourcetype credentials_error = private {
  1. source : string option;
  2. message : string;
}

Credential discovery, loading, or validation failure.

Sourcetype signing_error = private {
  1. message : string;
}

Request signing failure.

Sourcetype endpoint_error = private {
  1. uri : string option;
  2. message : string;
}

Endpoint resolution or validation failure.

Sourcetype transport = private {
  1. message : string;
  2. retryable : bool;
  3. cause : string option;
}

HTTP/runtime transport failure. cause is a compact runtime exception string when the adapter caught one.

Sourcetype service = private {
  1. status : int;
  2. code : string option;
  3. message : string option;
  4. request_id : string option;
  5. host_id : string option;
  6. headers : (string * string) list;
  7. body : string option;
}

AWS service error response.

Service values returned through public accessors and public diagnostics are safe for logs: secret-bearing headers are redacted and response bodies are replaced with a redaction marker. Use Unsafe_diagnostics when an implementor or test needs the raw service headers or body.

Sourcetype body = private {
  1. message : string;
  2. limit : int64 option;
}

Request or response body failure.

Sourcetype decode = private {
  1. message : string;
}

Response metadata or payload decoding failure.

Sourcetype timeout = private {
  1. operation : string option;
  2. message : string;
}

Operation, connection, request, or response timeout.

Sourcetype cancellation = private {
  1. reason : string option;
}

Caller or runtime cancellation.

Sourcetype retry_exhausted = private {
  1. attempts : int;
  2. max_attempts : int option;
  3. last_error : t option;
  4. message : string;
}

Retry policy exhaustion. last_error preserves the terminal failure when one is available.

Sourcetype not_supported = private {
  1. feature : string option;
  2. message : string;
}

Unsupported operation, feature, or runtime capability.

Sourcetype operation = private {
  1. service : string option;
  2. name : string;
  3. resource : string option;
}

High-level SDK operation context.

Sourcetype retry = private {
  1. attempt : int;
  2. max_attempts : int option;
  3. reason : string;
}

Retry context attached to the returned final error.

Sourcetype context = private
  1. | Message of string
  2. | Operation of operation
  3. | Retry of retry
  4. | Sexp of Base.Sexp.t

Additional diagnostic context. Public accessors return redacted context.

Sourcetype retry_class =
  1. | Retryable
  2. | Throttled
  3. | Auth
  4. | Conflict
  5. | Not_found
  6. | Fatal
  7. | Unknown

Coarse caller-handling class used by retry policy and applications.

Sourcetype kind = private
  1. | Validation of validation
  2. | Credentials of credentials_error
  3. | Signing of signing_error
  4. | Endpoint of endpoint_error
  5. | Transport of transport
  6. | Timeout of timeout
  7. | Cancelled of cancellation
  8. | Service of service
  9. | Body of body
  10. | Decode of decode
  11. | Retry_exhausted of retry_exhausted
  12. | Not_supported of not_supported
  13. | Multiple of t list
Sourceval kind : t -> kind

Return the redacted top-level error kind.

Sourceval context : t -> context list

Return the redacted context stack, newest context first.

Sourceval retry_class : t -> retry_class

Coarse retry/handling classification. retry_class aggregates Multiple errors by caller-handling priority: Auth > Throttled > Retryable > Conflict > Not_found > Fatal > Unknown. This means a retryable or throttled nested error can outrank a fatal nested validation/body/decode error.

Sourceval is_validation : t -> bool

true when t or a nested Multiple error contains validation failure.

Sourceval is_credentials : t -> bool

true when t or a nested Multiple error contains a credentials failure.

Sourceval is_endpoint : t -> bool

true when t or a nested Multiple error contains an endpoint failure.

Sourceval is_transport : t -> bool

true when t or a nested Multiple error contains a transport failure.

Sourceval is_timeout : t -> bool

true when t or a nested Multiple error contains a timeout.

Sourceval is_cancelled : t -> bool

true when t or a nested Multiple error contains SDK-level cancellation. Runtime-native cancellation such as Lwt.Canceled may be preserved as an exception instead of converted to Cancelled.

Sourceval validation_field : t -> string option

First validation field in t, if one is available.

Sourceval is_not_found : t -> bool

true when retry_class classifies t as Not_found.

Sourceval service_code : t -> string option

First AWS service error code in t, if one is available.

Sourceval service_status : t -> int option

First AWS service HTTP status in t, if one is available.

Sourceval sexp_of_validation : validation -> Base.Sexp.t
Sourceval sexp_of_credentials_error : credentials_error -> Base.Sexp.t
Sourceval sexp_of_signing_error : signing_error -> Base.Sexp.t
Sourceval sexp_of_endpoint_error : endpoint_error -> Base.Sexp.t
Sourceval sexp_of_transport : transport -> Base.Sexp.t
Sourceval sexp_of_service : service -> Base.Sexp.t
Sourceval sexp_of_body : body -> Base.Sexp.t
Sourceval sexp_of_decode : decode -> Base.Sexp.t
Sourceval sexp_of_timeout : timeout -> Base.Sexp.t
Sourceval sexp_of_cancellation : cancellation -> Base.Sexp.t
Sourceval sexp_of_retry_exhausted : retry_exhausted -> Base.Sexp.t
Sourceval sexp_of_not_supported : not_supported -> Base.Sexp.t
Sourceval sexp_of_operation : operation -> Base.Sexp.t
Sourceval sexp_of_retry : retry -> Base.Sexp.t
Sourceval sexp_of_context : context -> Base.Sexp.t
Sourceval sexp_of_retry_class : retry_class -> Base.Sexp.t
Sourceval sexp_of_kind : kind -> Base.Sexp.t
Sourceval sexp_of_t : t -> Base.Sexp.t

Render a redacted S-expression diagnostic.

Sourceval pp : Format.formatter -> t -> unit

Pretty-print a redacted human diagnostic.

Sourceval pp_sexp : Format.formatter -> t -> unit

Pretty-print the redacted S-expression diagnostic.

Sourceval to_string_hum : t -> string

Render a redacted human diagnostic string.

Sourceval to_sexp_string_hum : t -> string

Render a redacted S-expression diagnostic string.

Sourceval equal : t -> t -> bool

Structural equality on error values.

Sourcemodule Unsafe_diagnostics : sig ... end

Explicit escape hatch for raw diagnostic material.

Sourcemodule Producer : sig ... end

Producer-side error constructors.