dynoxide/

errors.rs

use serde::Serialize;
use std::collections::HashMap;
use std::fmt;

/// Per-item cancellation reason in a `TransactionCanceledException` response.
///
/// Real DynamoDB returns one reason per `TransactItem`, with `Code: "None"` for
/// items that would have succeeded.
#[derive(Debug, Clone, Default, Serialize)]
pub struct CancellationReason {
    #[serde(rename = "Code")]
    pub code: String,
    #[serde(rename = "Message", skip_serializing_if = "Option::is_none")]
    pub message: Option<String>,
    #[serde(
        rename = "Item",
        skip_serializing_if = "Option::is_none",
        serialize_with = "crate::set_order::item_in_hash_order"
    )]
    // Number sets in Java hash-set order here, as DynamoDB returns them;
    // pinned by set_order's every_response_item_field test.
    pub item: Option<HashMap<String, crate::types::AttributeValue>>,
}

/// DynamoDB error types.
///
/// Each variant corresponds to a DynamoDB API error, carrying a human-readable
/// message that matches DynamoDB's actual error messages.
///
/// Marked `#[non_exhaustive]` as of 0.10.0 (itself a breaking release), so
/// later variant additions stay non-breaking. Downstream `match` arms over
/// this enum must include a wildcard.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum DynoxideError {
    /// Table or resource not found.
    #[error("{0}")]
    ResourceNotFoundException(String),

    /// Table or resource already exists / is in use.
    #[error("{0}")]
    ResourceInUseException(String),

    /// Input validation failed.
    #[error("{0}")]
    ValidationException(String),

    /// An empty-string or empty-binary key value on a write. Serialises identically
    /// to `ValidationException`, but is a distinct variant so the transaction loops can
    /// surface it as a top-level error instead of a `ValidationError` cancellation
    /// reason (#95).
    #[error("{0}")]
    KeyEmptyValueValidation(String),

    /// A request-validation error that PutItem and UpdateItem wrap in the
    /// `1 validation error detected: ` envelope at their operation boundary.
    /// Serialises identically to `ValidationException` on every surface; the
    /// distinct variant only tags where the envelope applies.
    #[error("{0}")]
    EnvelopedValidation(String),

    /// Conditional check (ConditionExpression) failed on write.
    /// Optionally carries the existing item when `ReturnValuesOnConditionCheckFailure` is `ALL_OLD`.
    #[error("{0}")]
    ConditionalCheckFailedException(
        String,
        Option<HashMap<String, crate::types::AttributeValue>>,
    ),

    /// `ExecuteStatement`'s `ConditionalCheckFailedException` carrying the item
    /// `ReturnValuesOnConditionCheckFailure` asked for. DynamoDB writes this one
    /// with a capitalised `Message` and the item's number sets in hash order,
    /// as it writes the PartiQL operations' other items, where `PutItem`,
    /// `UpdateItem` and `DeleteItem` write `message` and numeric order
    /// (captured eu-west-2 and us-east-1, 2026-10-10). Only the HTTP and wasm
    /// dispatch seams build it, from a `ConditionalCheckFailedException`; the
    /// in-process API returns that variant, item included.
    #[error("{0}")]
    StatementConditionalCheckFailed(String, HashMap<String, crate::types::AttributeValue>),

    /// One or more transaction conditions failed.
    /// Carries the message and per-item cancellation reasons.
    #[error("{0}")]
    TransactionCanceledException(String, Vec<CancellationReason>),

    /// Item collection exceeded size limit (10 GB per partition key value).
    #[error("{0}")]
    ItemCollectionSizeLimitExceededException(String),

    /// Duplicate primary key on PartiQL INSERT (distinct from ConditionalCheckFailedException).
    #[error("{0}")]
    DuplicateItemException(String),

    /// Throughput exceeded (stored but not enforced: included for API fidelity).
    #[error("{0}")]
    ProvisionedThroughputExceededException(String),

    /// Request body deserialisation failed (malformed JSON, wrong types).
    #[error("{0}")]
    SerializationException(String),

    /// Too many concurrent operations or index updates.
    #[error("{0}")]
    LimitExceededException(String),

    /// Access denied (e.g. non-existent resource ARN in tag operations).
    #[error("{0}")]
    AccessDeniedException(String),

    /// Idempotent request token reused with different request content.
    #[error("{0}")]
    IdempotentParameterMismatchException(String),

    /// Catch-all for internal / unexpected errors (SQLite failures, etc.).
    #[error("{0}")]
    InternalServerError(String),

    /// A capability the active storage backend does not implement (for example
    /// streams or tags on the wasm backend). Serialises with the same
    /// `UnsupportedOperation` type and 501 status as an op the engine does not
    /// serve at all, so a client - and the conformance suite - reads both the
    /// same way: a scope gap, not a server fault. The 501 also keeps AWS SDK
    /// retry policies from re-sending a request that can never succeed.
    #[error("'{0}' is not supported by this build of the engine")]
    UnsupportedCapability(String),

    /// Type conversion error (e.g. wrong AttributeValue variant).
    #[error("Conversion error: {0}")]
    ConversionError(#[from] crate::types::ConversionError),

    /// SQLite error (converted from rusqlite).
    #[cfg(any(feature = "native-sqlite", feature = "_has-encryption"))]
    #[error("Internal error: {0}")]
    SqliteError(#[from] rusqlite::Error),

    /// OPFS is present in the browser but its pool could not be acquired
    /// (typically another tab holds the database). wasm backend only; carries a
    /// dynoxide-specific `__type` so a client can detect a busy database.
    #[cfg(feature = "wasm-sqlite")]
    #[error("{0}")]
    OpfsUnavailable(String),
}

/// Most backend failures (`BackendError`) are storage-level faults: a locked
/// database, an I/O error, a constraint the application layer did not
/// anticipate. None of those is part of DynamoDB's client-facing error
/// contract, so they surface as `InternalServerError` (HTTP 500), matching how
/// a raw `rusqlite::Error` surfaces via `SqliteError`.
///
/// There are two exceptions. The first is `BackendError::Validation`: a
/// backend method such as `set_tags` enforces a client-facing limit (the
/// 50-tag cap) and raises a `ValidationException`. That crosses the trait
/// boundary as `BackendError::Validation` and is restored here to its
/// `ValidationException` (HTTP 400) so the envelope is unchanged from calling
/// `Storage` directly. The second is `BackendError::Unsupported`, which maps
/// to `DynoxideError::UnsupportedCapability` (HTTP 501, the
/// `com.dynoxide.wasm#UnsupportedOperation` envelope) so a capability gap
/// reads as scope, not a server fault.
///
/// A one-way `From` is deliberate rather than merging the two types:
/// `BackendError` is the narrow storage vocabulary, `DynoxideError` the wider
/// API vocabulary. A merge is deferred.
impl From<crate::storage_backend::BackendError> for DynoxideError {
    fn from(err: crate::storage_backend::BackendError) -> Self {
        use crate::storage_backend::BackendError;
        match err {
            BackendError::Validation(msg) => DynoxideError::ValidationException(msg),
            BackendError::Unsupported { capability } => {
                DynoxideError::UnsupportedCapability(capability.to_string())
            }
            #[cfg(feature = "wasm-sqlite")]
            BackendError::OpfsUnavailable(msg) => DynoxideError::OpfsUnavailable(msg),
            other => DynoxideError::InternalServerError(other.to_string()),
        }
    }
}

/// The `__type` carried when the engine cannot do what was asked. Shared by
/// the wasm op-level `UnsupportedOperation` envelope and
/// `DynoxideError::UnsupportedCapability`, so a client detects "the engine
/// cannot do this" with one type either way. Namespaced so it cannot collide
/// with a real DynamoDB `__type`.
pub(crate) const UNSUPPORTED_TYPE: &str = "com.dynoxide.wasm#UnsupportedOperation";

impl DynoxideError {
    /// Returns the DynamoDB `__type` string for this error.
    pub fn error_type(&self) -> &'static str {
        match self {
            DynoxideError::ResourceNotFoundException(_) => {
                "com.amazonaws.dynamodb.v20120810#ResourceNotFoundException"
            }
            DynoxideError::ResourceInUseException(_) => {
                "com.amazonaws.dynamodb.v20120810#ResourceInUseException"
            }
            DynoxideError::ValidationException(_)
            | DynoxideError::KeyEmptyValueValidation(_)
            | DynoxideError::EnvelopedValidation(_) => {
                "com.amazon.coral.validate#ValidationException"
            }
            DynoxideError::ConditionalCheckFailedException(..)
            | DynoxideError::StatementConditionalCheckFailed(..) => {
                "com.amazonaws.dynamodb.v20120810#ConditionalCheckFailedException"
            }
            DynoxideError::TransactionCanceledException(..) => {
                "com.amazonaws.dynamodb.v20120810#TransactionCanceledException"
            }
            DynoxideError::DuplicateItemException(_) => {
                "com.amazonaws.dynamodb.v20120810#DuplicateItemException"
            }
            DynoxideError::ItemCollectionSizeLimitExceededException(_) => {
                "com.amazonaws.dynamodb.v20120810#ItemCollectionSizeLimitExceededException"
            }
            DynoxideError::ProvisionedThroughputExceededException(_) => {
                "com.amazonaws.dynamodb.v20120810#ProvisionedThroughputExceededException"
            }
            DynoxideError::SerializationException(_) => {
                "com.amazon.coral.service#SerializationException"
            }
            DynoxideError::LimitExceededException(_) => {
                "com.amazonaws.dynamodb.v20120810#LimitExceededException"
            }
            DynoxideError::AccessDeniedException(_) => {
                "com.amazonaws.dynamodb.v20120810#AccessDeniedException"
            }
            DynoxideError::IdempotentParameterMismatchException(_) => {
                "com.amazonaws.dynamodb.v20120810#IdempotentParameterMismatchException"
            }
            DynoxideError::ConversionError(_) => "com.amazon.coral.validate#ValidationException",
            DynoxideError::InternalServerError(_) => {
                "com.amazonaws.dynamodb.v20120810#InternalServerError"
            }
            // The same sentinel the op-level 501 envelope carries, so a client
            // detects "the engine cannot do this" with one type either way.
            DynoxideError::UnsupportedCapability(_) => UNSUPPORTED_TYPE,
            #[cfg(any(feature = "native-sqlite", feature = "_has-encryption"))]
            DynoxideError::SqliteError(_) => "com.amazonaws.dynamodb.v20120810#InternalServerError",
            #[cfg(feature = "wasm-sqlite")]
            DynoxideError::OpfsUnavailable(_) => "com.dynoxide.wasm#OpfsUnavailable",
        }
    }

    /// Returns the short error code used in `BatchExecuteStatement` per-statement errors.
    ///
    /// These are the short-form codes that DynamoDB uses in `BatchStatementError.Code`,
    /// as opposed to the fully qualified `__type` strings from `error_type()`.
    pub fn short_error_code(&self) -> &'static str {
        match self {
            DynoxideError::ResourceNotFoundException(_) => "ResourceNotFound",
            DynoxideError::ResourceInUseException(_) => "ResourceInUse",
            DynoxideError::ValidationException(_)
            | DynoxideError::KeyEmptyValueValidation(_)
            | DynoxideError::EnvelopedValidation(_)
            | DynoxideError::ConversionError(_) => "ValidationError",
            DynoxideError::ConditionalCheckFailedException(..)
            | DynoxideError::StatementConditionalCheckFailed(..) => "ConditionalCheckFailed",
            DynoxideError::TransactionCanceledException(..) => "TransactionConflict",
            DynoxideError::DuplicateItemException(_) => "DuplicateItem",
            DynoxideError::ItemCollectionSizeLimitExceededException(_) => {
                "ItemCollectionSizeLimitExceeded"
            }
            DynoxideError::ProvisionedThroughputExceededException(_) => {
                "ProvisionedThroughputExceeded"
            }
            DynoxideError::AccessDeniedException(_) => "AccessDenied",
            DynoxideError::IdempotentParameterMismatchException(_) => "IdempotentParameterMismatch",
            DynoxideError::SerializationException(_) => "SerializationError",
            DynoxideError::LimitExceededException(_) => "RequestLimitExceeded",
            DynoxideError::InternalServerError(_) => "InternalServerError",
            DynoxideError::UnsupportedCapability(_) => "UnsupportedOperation",
            #[cfg(any(feature = "native-sqlite", feature = "_has-encryption"))]
            DynoxideError::SqliteError(_) => "InternalServerError",
            #[cfg(feature = "wasm-sqlite")]
            DynoxideError::OpfsUnavailable(_) => "OpfsUnavailable",
        }
    }

    /// Returns the HTTP status code for this error.
    pub fn status_code(&self) -> u16 {
        match self {
            DynoxideError::InternalServerError(_) => 500,
            #[cfg(any(feature = "native-sqlite", feature = "_has-encryption"))]
            DynoxideError::SqliteError(_) => 500,
            // 501 for the same reason the op-level envelope uses it: "not
            // implemented" is a definite answer about scope, and it sits
            // outside the status codes AWS SDK retry policies re-send.
            DynoxideError::UnsupportedCapability(_) => 501,
            _ => 400,
        }
    }

    /// Convert to a DynamoDB-compatible JSON error response body.
    pub fn to_response(&self) -> ErrorResponse {
        let item = match self {
            DynoxideError::ConditionalCheckFailedException(_, item) => item.clone(),
            DynoxideError::StatementConditionalCheckFailed(_, item) => Some(item.clone()),
            _ => None,
        };
        ErrorResponse {
            error_type: self.error_type().to_string(),
            message: self.to_string(),
            item,
        }
    }

    /// Serialise to the JSON body `operation` answers with.
    ///
    /// SearchVectors is served by its own endpoint, which writes every error
    /// as `__type` then a lowercase `message`, a `SerializationException`
    /// included (captured eu-west-2 and us-east-1, 23 October 2026). Every
    /// other operation gets [`to_json`](Self::to_json).
    #[cfg(any(feature = "http-server", feature = "wasm-sqlite", test))]
    pub(crate) fn to_json_for(&self, operation: &str) -> String {
        match self {
            DynoxideError::SerializationException(_) if operation == "SearchVectors" => {
                let message = self.to_string();
                let mut m = serde_json::Map::new();
                m.insert(
                    "__type".to_string(),
                    serde_json::Value::String(self.error_type().to_string()),
                );
                if !message.is_empty() {
                    m.insert("message".to_string(), serde_json::Value::String(message));
                }
                serde_json::to_string(&m).unwrap_or_default()
            }
            _ => self.to_json(),
        }
    }

    /// Serialise to DynamoDB-compatible JSON string.
    ///
    /// `SerializationException` and `TransactionCanceledException` use
    /// `Message` (capital M) while all other errors use `message` (lowercase),
    /// matching real DynamoDB behaviour.
    pub fn to_json(&self) -> String {
        let error_type = self.error_type();
        let message = self.to_string();

        match self {
            DynoxideError::TransactionCanceledException(_, reasons) => {
                let mut m = serde_json::Map::new();
                m.insert(
                    "__type".to_string(),
                    serde_json::Value::String(error_type.to_string()),
                );
                m.insert("Message".to_string(), serde_json::Value::String(message));
                if let Ok(reasons_val) = serde_json::to_value(reasons) {
                    m.insert("CancellationReasons".to_string(), reasons_val);
                }
                serde_json::to_string(&m).unwrap_or_default()
            }
            DynoxideError::StatementConditionalCheckFailed(_, item) => {
                let mut m = serde_json::Map::new();
                m.insert(
                    "__type".to_string(),
                    serde_json::Value::String(error_type.to_string()),
                );
                m.insert("Message".to_string(), serde_json::Value::String(message));
                if let Ok(item) = serde_json::to_value(crate::set_order::HashOrderedItem(item)) {
                    m.insert("Item".to_string(), item);
                }
                serde_json::to_string(&m).unwrap_or_default()
            }
            DynoxideError::SerializationException(_) => {
                let mut m = serde_json::Map::new();
                m.insert(
                    "__type".to_string(),
                    serde_json::Value::String(error_type.to_string()),
                );
                // DynamoDB leaves the message out altogether when it has none
                // to give, as for a list where a boolean belongs.
                if !message.is_empty() {
                    m.insert("Message".to_string(), serde_json::Value::String(message));
                }
                serde_json::to_string(&m).unwrap_or_default()
            }
            _ => {
                let resp = self.to_response();
                serde_json::to_string(&resp).unwrap_or_default()
            }
        }
    }
}

/// DynamoDB JSON error response body.
#[derive(Debug, Serialize)]
pub struct ErrorResponse {
    #[serde(rename = "__type")]
    pub error_type: String,
    #[serde(rename = "message")]
    pub message: String,
    #[serde(rename = "Item", skip_serializing_if = "Option::is_none")]
    // Number sets in numeric order here, as DynamoDB returns them;
    // pinned by set_order's every_response_item_field test.
    pub item: Option<HashMap<String, crate::types::AttributeValue>>,
}

impl fmt::Display for ErrorResponse {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", serde_json::to_string(self).unwrap_or_default())
    }
}

/// Convenience alias.
pub type Result<T> = std::result::Result<T, DynoxideError>;

/// The error as `operation` puts it on the wire, for the HTTP and wasm
/// dispatch seams: `ExecuteStatement`'s condition failure carrying an item is
/// written in its own shape (see
/// [`DynoxideError::StatementConditionalCheckFailed`]). Every other error
/// passes through unchanged.
#[cfg(any(feature = "http-server", feature = "wasm-sqlite", test))]
pub(crate) fn for_operation(operation: &str, err: DynoxideError) -> DynoxideError {
    match (operation, err) {
        (
            "ExecuteStatement",
            DynoxideError::ConditionalCheckFailedException(message, Some(item)),
        ) => DynoxideError::StatementConditionalCheckFailed(message, item),
        (_, err) => err,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_error_response_format() {
        let err = DynoxideError::ResourceNotFoundException(
            "Requested resource not found: Table: NonExistent not found".to_string(),
        );
        let resp = err.to_response();
        let json = serde_json::to_string(&resp).unwrap();

        assert!(json.contains("\"__type\""));
        assert!(json.contains("ResourceNotFoundException"));
        assert!(json.contains("NonExistent not found"));
    }

    #[test]
    fn test_status_codes() {
        assert_eq!(
            DynoxideError::ResourceNotFoundException("".into()).status_code(),
            400
        );
        assert_eq!(
            DynoxideError::ResourceInUseException("".into()).status_code(),
            400
        );
        assert_eq!(
            DynoxideError::ValidationException("".into()).status_code(),
            400
        );
        assert_eq!(
            DynoxideError::ConditionalCheckFailedException("".into(), None).status_code(),
            400
        );
        assert_eq!(
            DynoxideError::TransactionCanceledException("".into(), vec![]).status_code(),
            400
        );
        assert_eq!(
            DynoxideError::InternalServerError("".into()).status_code(),
            500
        );
    }

    #[test]
    fn test_key_empty_value_validation_is_wire_identical_to_validation_exception() {
        // The variant must be indistinguishable from ValidationException on every wire
        // surface, for both the empty-string and empty-binary messages it now carries.
        let messages = [
            "One or more parameter values are not valid. The AttributeValue for a key \
             attribute cannot contain an empty string value. Key: pk",
            "One or more parameter values are not valid. The AttributeValue for a key \
             attribute cannot contain an empty binary value. Key: pk",
        ];
        for msg in messages {
            let empty = DynoxideError::KeyEmptyValueValidation(msg.to_string());
            let plain = DynoxideError::ValidationException(msg.to_string());
            assert_eq!(empty.status_code(), plain.status_code());
            assert_eq!(empty.error_type(), plain.error_type());
            assert_eq!(empty.short_error_code(), plain.short_error_code());
            assert_eq!(empty.to_json(), plain.to_json());
            assert_eq!(empty.to_string(), plain.to_string());
        }
    }

    #[test]
    fn test_enveloped_validation_is_wire_identical_to_validation_exception() {
        // The variant must be indistinguishable from ValidationException on every wire
        // surface; only the operation boundary treats it specially.
        let msg = "One or more parameter values were invalid: \
                   Type mismatch for key pk expected: S actual: N";
        let enveloped = DynoxideError::EnvelopedValidation(msg.to_string());
        let plain = DynoxideError::ValidationException(msg.to_string());
        assert_eq!(enveloped.status_code(), plain.status_code());
        assert_eq!(enveloped.error_type(), plain.error_type());
        assert_eq!(enveloped.short_error_code(), plain.short_error_code());
        assert_eq!(enveloped.to_json(), plain.to_json());
        assert_eq!(enveloped.to_string(), plain.to_string());
    }

    #[test]
    fn test_error_type_strings() {
        let err = DynoxideError::ValidationException("bad input".into());
        assert_eq!(
            err.error_type(),
            "com.amazon.coral.validate#ValidationException"
        );
    }

    #[cfg(any(feature = "native-sqlite", feature = "_has-encryption"))]
    #[test]
    fn test_sqlite_error_maps_to_internal() {
        let sqlite_err = rusqlite::Error::QueryReturnedNoRows;
        let err = DynoxideError::from(sqlite_err);
        assert_eq!(err.status_code(), 500);
        assert!(err.error_type().contains("InternalServerError"));
    }

    // Error-envelope fidelity for the wasm backend.
    //
    // Client-facing envelopes (ResourceNotFound, ConditionalCheckFailed,
    // Validation, ...) are raised by the shared, generic action handlers, so
    // they are backend-independent by construction. The only backend-specific
    // boundary is `From<BackendError> for DynoxideError`, exercised here: the
    // wasm backend's storage faults must land on the same envelopes the native
    // rusqlite path produces.
    #[test]
    fn test_backend_error_envelopes_match_native() {
        use crate::storage_backend::BackendError;

        // A client-facing validation limit crosses the boundary as a 400.
        let v: DynoxideError = BackendError::Validation("too many tags".into()).into();
        assert_eq!(v.status_code(), 400);
        assert_eq!(
            v.error_type(),
            "com.amazon.coral.validate#ValidationException"
        );

        // Unsupported (e.g. streams or tags on wasm) surfaces as the same
        // typed 501 the op-level envelope uses, with a message the conformance
        // suite classifies as a scope gap ("is not supported") rather than a
        // server fault. A 500 here would be retried by AWS SDKs, and a retry
        // of a capability refusal can never succeed.
        let u: DynoxideError = BackendError::Unsupported { capability: "ttl" }.into();
        assert_eq!(u.status_code(), 501);
        assert_eq!(u.error_type(), "com.dynoxide.wasm#UnsupportedOperation");
        assert!(u.to_string().contains("'ttl' is not supported"));

        // Every other storage fault maps to a 500, matching the native
        // `rusqlite::Error -> SqliteError -> InternalServerError` path.
        for e in [
            BackendError::NotADatabase,
            BackendError::Locked,
            BackendError::Constraint("constraint".into()),
            BackendError::Io("io".into()),
            BackendError::Other("sqlite-wasm: boom".into()),
        ] {
            let d: DynoxideError = e.into();
            assert_eq!(d.status_code(), 500);
            assert!(d.error_type().contains("InternalServerError"));
        }
    }

    #[test]
    fn test_error_response_json_structure() {
        let err = DynoxideError::ValidationException("1 validation error detected".to_string());
        let resp = err.to_response();
        let json: serde_json::Value = serde_json::to_value(&resp).unwrap();

        assert!(json.get("__type").is_some());
        assert!(json.get("message").is_some());
        assert_eq!(
            json["__type"],
            "com.amazon.coral.validate#ValidationException"
        );
        assert_eq!(json["message"], "1 validation error detected");
    }

    #[test]
    fn test_short_error_codes() {
        assert_eq!(
            DynoxideError::ResourceNotFoundException("".into()).short_error_code(),
            "ResourceNotFound"
        );
        assert_eq!(
            DynoxideError::ValidationException("".into()).short_error_code(),
            "ValidationError"
        );
        assert_eq!(
            DynoxideError::ConditionalCheckFailedException("".into(), None).short_error_code(),
            "ConditionalCheckFailed"
        );
        assert_eq!(
            DynoxideError::DuplicateItemException("".into()).short_error_code(),
            "DuplicateItem"
        );
        assert_eq!(
            DynoxideError::InternalServerError("".into()).short_error_code(),
            "InternalServerError"
        );
    }

    #[test]
    fn test_transaction_cancelled_json_has_cancellation_reasons() {
        let reasons = vec![
            CancellationReason {
                code: "ConditionalCheckFailed".to_string(),
                message: Some("The conditional request failed".to_string()),
                item: None,
            },
            CancellationReason {
                code: "None".to_string(),
                message: None,
                item: None,
            },
        ];
        let err = DynoxideError::TransactionCanceledException(
            "Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]".to_string(),
            reasons,
        );
        let json_str = err.to_json();
        let json: serde_json::Value = serde_json::from_str(&json_str).unwrap();

        // CancellationReasons must be a top-level field
        assert!(json.get("CancellationReasons").is_some());
        let reasons = json["CancellationReasons"].as_array().unwrap();
        assert_eq!(reasons.len(), 2);
        assert_eq!(reasons[0]["Code"], "ConditionalCheckFailed");
        assert_eq!(reasons[1]["Code"], "None");

        // Uses capital Message (not lowercase)
        assert!(json.get("Message").is_some());
        assert!(json.get("message").is_none());
    }

    #[test]
    fn test_backend_error_maps_to_internal() {
        use crate::storage_backend::BackendError;
        let err: DynoxideError = BackendError::Locked.into();
        assert_eq!(err.status_code(), 500);
        assert!(err.error_type().contains("InternalServerError"));
        assert!(err.to_string().contains("locked"));
    }

    /// SearchVectors' own endpoint writes a SerializationException as
    /// `__type` then a lowercase `message`, leaving the message out when it
    /// has none (captured eu-west-2 and us-east-1, 23 October 2026).
    #[test]
    fn search_vectors_writes_a_serialization_exception_with_a_lowercase_message() {
        let err = DynoxideError::SerializationException(
            "invalid type: null, expected a string at line 1 column 20".to_string(),
        );
        assert_eq!(
            err.to_json_for("SearchVectors"),
            r#"{"__type":"com.amazon.coral.service#SerializationException","message":"invalid type: null, expected a string at line 1 column 20"}"#
        );
        assert_eq!(
            DynoxideError::SerializationException(String::new()).to_json_for("SearchVectors"),
            r#"{"__type":"com.amazon.coral.service#SerializationException"}"#
        );
    }

    /// Every other operation, and every other error from SearchVectors, keeps
    /// the body `to_json` writes.
    #[test]
    fn other_operations_and_errors_keep_the_shared_body() {
        let serialization = DynoxideError::SerializationException("Unexpected field type".into());
        for operation in ["Query", "CreateTable", "GetItem"] {
            assert_eq!(
                serialization.to_json_for(operation),
                serialization.to_json()
            );
        }
        let validation = DynoxideError::ValidationException("bad".into());
        assert_eq!(
            validation.to_json_for("SearchVectors"),
            validation.to_json()
        );
        assert!(
            serialization
                .to_json()
                .contains(r#""Message":"Unexpected field type""#)
        );
    }
}