Cosmos: Expose a CosmosError type instead of bubbling up azure_core::Error

[tvaron3]

Feature Summary

Expose a CosmosError type on the public API surface instead of returning azure_core::Error directly from Cosmos client methods.

Feature Description

All Cosmos client methods currently return azure_core::Result<T> (i.e., Result<T, azure_core::Error>). This leaks an internal dependency and makes it difficult for callers to access Cosmos-specific error details without downcasting.

A dedicated CosmosError type would:

• Provide direct access to Cosmos-specific error metadata: HTTP status code, substatus code, activity ID, request charge (RU consumption), and retry-after duration.
• Avoid requiring callers to downcast from azure_core::Error to inspect service error details.
• Allow pattern matching on structured error variants (e.g., throttling, conflict, not found) instead of parsing strings or checking HTTP status codes.
• Follow the precedent set by other Azure SDKs (e.g., Java's CosmosException, .NET's CosmosException, Python's CosmosHttpResponseError).

Use Case

// Today: awkward downcasting or status code inspection
match client.read_item::<MyDoc>(id, pk, None).await {
    Err(e) => {
        // No structured way to get substatus, activity ID, or request charge
    }
    Ok(response) => { /* ... */ }
}

// Proposed: structured error with Cosmos metadata
match client.read_item::<MyDoc>(id, pk, None).await {
    Err(e) => {
        println!("Status: {}", e.status());
        println!("Substatus: {:?}", e.substatus());
        println!("Activity ID: {:?}", e.activity_id());
        println!("Request charge: {:?}", e.request_charge());
    }
    Ok(response) => { /* ... */ }
}

Alternatives

• Continue using azure_core::Error with downcasting — works but is unergonomic.
• Provide extension traits on azure_core::Error for Cosmos metadata — avoids a new type but still requires the caller to know about the trait.

Additional Context

No response