Public declaration syntax from forge-rs/crates/forge-provider-openai/src/error.rs
Original source SHA-256: 6b0f971c10b6415cceb05f77a3e0a5d6de346f65a61dd121e746fea1e61312c1
Function bodies and constant values are omitted. This is not the complete implementation.

Source line 30
#[derive(Debug, Error)]
pub enum OpenAiError {
    /// The OpenAI API returned an HTTP error response.
    ///
    /// Common status codes:
    /// - 400: malformed request (check message format)
    /// - 401: invalid API key
    /// - 403: insufficient permissions
    /// - 404: model not found
    /// - 429: rate limited
    /// - 500+: server error (retryable)
    #[error(
        "OpenAI API returned HTTP {status}: {body} (check request format and API key permissions)"
    )]
    HttpError {
        /// The HTTP status code.
        status: u16,
        /// The response body (may contain OpenAI error details).
        body: String,
    },

    /// Failed to connect to the OpenAI API endpoint.
    ///
    /// Check network connectivity, firewall rules, and the configured base URL.
    #[error("failed to connect to OpenAI API at '{url}': {reason} (check network connectivity and base_url configuration)")]
    ConnectionFailed {
        /// The URL that was being connected to.
        url: String,
        /// The underlying connection error.
        reason: String,
    },

    /// The request timed out waiting for a response.
    ///
    /// Consider increasing `timeout_seconds` in `OpenAiConfig` or reducing
    /// `max_tokens` to speed up generation.
    #[error("OpenAI API request to '{url}' timed out after {timeout_seconds}s (consider increasing timeout_seconds in OpenAiConfig or reducing max_tokens)")]
    Timeout {
        /// The URL that timed out.
        url: String,
        /// The configured timeout in seconds.
        timeout_seconds: u64,
    },

    /// The API response could not be parsed.
    ///
    /// This typically indicates an API version mismatch or an unexpected
    /// response format. Check the OpenAI API changelog for breaking changes.
    #[error("invalid response from OpenAI API: {reason} (this may indicate an API version mismatch; check the OpenAI API changelog)")]
    InvalidResponse {
        /// Description of what was wrong with the response.
        reason: String,
    },

    /// The API returned a rate limit error (HTTP 429).
    ///
    /// The provider will automatically retry with exponential backoff. If this
    /// error surfaces, all retries have been exhausted.
    #[error("OpenAI API rate limited; all retries exhausted{}", match .retry_after_ms {
        Some(ms) => format!(" (server suggested retry after {ms}ms)"),
        None => String::new(),
    })]
    RateLimited {
        /// Milliseconds to wait before retrying, if provided by the server.
        retry_after_ms: Option<u64>,
    },

    /// Authentication failed (HTTP 401).
    ///
    /// The API key is invalid, expired, or missing.
    #[error("OpenAI API authentication failed: {hint}")]
    AuthenticationFailed {
        /// Actionable hint for resolving the auth issue.
        hint: String,
    },

    /// An error occurred while parsing the SSE stream.
    ///
    /// This may indicate a network interruption during streaming or an
    /// unexpected stream format.
    #[error("OpenAI streaming error: {reason}")]
    StreamError {
        /// Description of the stream parsing failure.
        reason: String,
    },

    /// JSON serialization or deserialization failed.
    ///
    /// This typically means a request or response struct is malformed.
    #[error("JSON serialization error: {0}")]
    SerializationError(#[from] serde_json::Error),

    /// The request could not be constructed.
    ///
    /// This indicates an internal error in request building.
    #[error("failed to build HTTP request: {reason}")]
    RequestBuildError {
        /// Description of the request construction failure.
        reason: String,
    },
}