refactor: deep harmonization of exception hierarchy, field names, and API surface

- Python: rename ApiException fields (status→code, reason→message,
  body→response_body, headers→response_headers), remove legacy data field
- Python/Ruby: add response_headers parameter to all exception subclasses
  and pass actual headers from base_api throw methods
- Java: reduce ApiException from 9 constructors to 3, pass response
  headers (was null) in throwApiException, fix NullAway in DefaultApiClient
- PHP: align error message format to "API returned status code {code}",
  fix responseHeaders doc type to array<string, string>, flatten headers
- Java/C#/PHP: standardize Configuration.server() parameter name to
  serverConfig

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mridang

src/main/resources/templates/csharp/configuration.mustache

@@ -108,13 +108,13 @@ public sealed class ConfigurationBuilder
     /// <summary>
     /// Set the base URL by resolving a server configuration with optional variable overrides.
     /// </summary>
-    /// <param name="server">The server configuration to resolve.</param>
+    /// <param name="serverConfig">The server configuration to resolve.</param>
     /// <param name="variables">Optional variable overrides. Defaults are used for unspecified variables.</param>
     /// <returns>This builder.</returns>
-    public ConfigurationBuilder Server(ServerConfiguration server, Dictionary<string, string>? variables = null)
+    public ConfigurationBuilder Server(ServerConfiguration serverConfig, Dictionary<string, string>? variables = null)
     {
-        ArgumentNullException.ThrowIfNull(server);
-        _baseUrl = server.GetUrl(variables ?? []);
+        ArgumentNullException.ThrowIfNull(serverConfig);
+        _baseUrl = serverConfig.GetUrl(variables ?? []);
         return this;
     }
 

src/main/resources/templates/java/api_exception.mustache

@@ -14,21 +14,6 @@ public class ApiException extends Exception {
     @Nullable private final String responseBody;
     @Nullable private final transient Object errorBody;
 
-    public ApiException() {
-        this.code = 0;
-        this.responseHeaders = null;
-        this.responseBody = null;
-        this.errorBody = null;
-    }
-
-    public ApiException(Throwable throwable) {
-        super(throwable);
-        this.code = 0;
-        this.responseHeaders = null;
-        this.responseBody = null;
-        this.errorBody = null;
-    }
-
     public ApiException(String message) {
         super(message);
         this.code = 0;
@@ -37,54 +22,12 @@ public class ApiException extends Exception {
         this.errorBody = null;
     }
 
-    public ApiException(
-            String message,
-            @Nullable Throwable throwable,
-            int code,
-            @Nullable Map<String, String> responseHeaders,
-            @Nullable String responseBody) {
-        super(message, throwable);
-        this.code = code;
-        this.responseHeaders = responseHeaders;
-        this.responseBody = responseBody;
-        this.errorBody = null;
-    }
-
-    public ApiException(
-            String message,
-            int code,
-            @Nullable Map<String, String> responseHeaders,
-            @Nullable String responseBody) {
-        this(message, null, code, responseHeaders, responseBody);
-    }
-
-    public ApiException(
-            String message,
-            @Nullable Throwable throwable,
-            int code,
-            @Nullable Map<String, String> responseHeaders) {
-        this(message, throwable, code, responseHeaders, null);
-    }
-
-    public ApiException(int code, Map<String, String> responseHeaders, String responseBody) {
-        this(
-                "Response Code: " + code + " Response Body: " + responseBody,
-                null,
-                code,
-                responseHeaders,
-                responseBody);
-    }
-
-    public ApiException(int code, String message) {
-        this(message, null, code, null, null);
-    }
-
     public ApiException(
             int code,
             String message,
             @Nullable Map<String, String> responseHeaders,
             @Nullable String responseBody) {
-        this(message, null, code, responseHeaders, responseBody);
+        this(code, message, responseHeaders, responseBody, null);
     }
 
     public ApiException(

src/main/resources/templates/java/base_api.mustache

@@ -275,6 +275,7 @@ public abstract class BaseApi {
         int code = response.statusCode();
         String message = "API returned status code " + code;
         String body = response.body();
+        Map<String, String> headers = response.headers();
 
         Object errorBody = null;
         if (body != null && !body.isEmpty()) {
@@ -287,22 +288,22 @@ public abstract class BaseApi {
 
         if (code >= 400 && code < 500) {
             throw switch (code) {
-                case 400 -> new BadRequestException(message, null, body, errorBody);
-                case 401 -> new UnauthorizedException(message, null, body, errorBody);
-                case 403 -> new ForbiddenException(message, null, body, errorBody);
-                case 404 -> new NotFoundException(message, null, body, errorBody);
-                case 409 -> new ConflictException(message, null, body, errorBody);
-                case 422 -> new UnprocessableEntityException(message, null, body, errorBody);
-                default  -> new ClientException(code, message, null, body, errorBody);
+                case 400 -> new BadRequestException(message, headers, body, errorBody);
+                case 401 -> new UnauthorizedException(message, headers, body, errorBody);
+                case 403 -> new ForbiddenException(message, headers, body, errorBody);
+                case 404 -> new NotFoundException(message, headers, body, errorBody);
+                case 409 -> new ConflictException(message, headers, body, errorBody);
+                case 422 -> new UnprocessableEntityException(message, headers, body, errorBody);
+                default  -> new ClientException(code, message, headers, body, errorBody);
             };
         }
         if (code >= 500) {
             throw switch (code) {
-                case 500 -> new InternalServerErrorException(message, null, body, errorBody);
-                default  -> new ServerException(code, message, null, body, errorBody);
+                case 500 -> new InternalServerErrorException(message, headers, body, errorBody);
+                default  -> new ServerException(code, message, headers, body, errorBody);
             };
         }
-        throw new ApiException(code, message, null, body);
+        throw new ApiException(code, message, headers, body);
     }
 
     /**

src/main/resources/templates/java/configuration.mustache

@@ -143,23 +143,23 @@ public final class Configuration {
          * use their default values. Enum validation is performed by
          * {@link ServerConfiguration#getUrl(Map)}.
          *
-         * @param server    the server configuration to use
-         * @param variables variable overrides (may be null for defaults)
+         * @param serverConfig the server configuration to use
+         * @param variables    variable overrides (may be null for defaults)
          * @return this builder
          */
-        public Builder server(ServerConfiguration server, @Nullable Map<String, String> variables) {
-            this.baseUrl = server.getUrl(variables != null ? variables : Map.of());
+        public Builder server(ServerConfiguration serverConfig, @Nullable Map<String, String> variables) {
+            this.baseUrl = serverConfig.getUrl(variables != null ? variables : Map.of());
             return this;
         }
 
         /**
          * Use a server configuration with default variables to set the base URL.
          *
-         * @param server the server configuration to use
+         * @param serverConfig the server configuration to use
          * @return this builder
          */
-        public Builder server(ServerConfiguration server) {
-            return server(server, null);
+        public Builder server(ServerConfiguration serverConfig) {
+            return server(serverConfig, null);
         }
 
         /**

src/main/resources/templates/java/default_api_client.mustache

@@ -219,10 +219,10 @@ public final class DefaultApiClient implements ApiClient {
                     responseBody,
                     responseHeaders);
         } catch (IOException e) {
-            throw new ApiException(e);
+            throw new ApiException(e.toString());
         } catch (InterruptedException e) {
             Thread.currentThread().interrupt();
-            throw new ApiException(e);
+            throw new ApiException(e.toString());
         }
     }
 

src/main/resources/templates/php/api_exception.mustache

@@ -18,7 +18,7 @@ class ApiException extends Exception
     /**
      * The HTTP headers of the server response.
      *
-     * @var string[][]|null
+     * @var array<string, string>|null
      */
     protected ?array $responseHeaders;
 
@@ -28,7 +28,7 @@ class ApiException extends Exception
     protected mixed $errorBody;
 
     /**
-     * @param string[][]|null $responseHeaders HTTP response headers
+     * @param array<string, string>|null $responseHeaders HTTP response headers
      */
     public function __construct(
         string $message = "",
@@ -46,7 +46,7 @@ class ApiException extends Exception
     /**
      * Gets the HTTP response headers.
      *
-     * @return string[][]|null HTTP response headers
+     * @return array<string, string>|null HTTP response headers
      */
     public function getResponseHeaders(): ?array
     {

src/main/resources/templates/php/base_api.mustache

@@ -197,8 +197,8 @@ class BaseApi
     private function throwApiException(ApiResponse $response): never
     {
         $code = $response->statusCode;
-        $message = sprintf('[%d] Error', $code);
-        $headers = $response->headers;
+        $message = "API returned status code $code";
+        $headers = array_map(fn(array $values): string => $values[0] ?? '', $response->headers);
         $body = $response->body;
 
         $errorBody = null;

src/main/resources/templates/php/configuration_builder.mustache

@@ -60,13 +60,13 @@ final class ConfigurationBuilder
      * Enum validation is performed by {@see ServerConfiguration::getUrl()}.
      * If the user also calls baseUrl() after server(), the explicit baseUrl wins (last-write-wins).
      *
-     * @param ServerConfiguration       $server    the server configuration to resolve
-     * @param array<string, string> $variables variable name to value overrides
+     * @param ServerConfiguration       $serverConfig the server configuration to resolve
+     * @param array<string, string> $variables    variable name to value overrides
      * @return self this builder
      */
-    public function server(ServerConfiguration $server, array $variables = []): self
+    public function server(ServerConfiguration $serverConfig, array $variables = []): self
     {
-        $this->baseUrl = $server->getUrl($variables);
+        $this->baseUrl = $serverConfig->getUrl($variables);
         return $this;
     }
 

src/main/resources/templates/python/base_api.mustache

@@ -225,6 +225,7 @@ class BaseApi:
         code = response.status_code
         message = f'API returned status code {code}'
         body = response.body
+        headers = dict(response.headers) if response.headers else None
 
         error_body = None
         if body:
@@ -235,20 +236,20 @@ class BaseApi:
 
         if 400 <= code < 500:
             if code == 400:
-                raise BadRequestException(reason=message, body=body, error_body=error_body)
+                raise BadRequestException(message=message, response_body=body, response_headers=headers, error_body=error_body)
             if code == 401:
-                raise UnauthorizedException(reason=message, body=body, error_body=error_body)
+                raise UnauthorizedException(message=message, response_body=body, response_headers=headers, error_body=error_body)
             if code == 403:
-                raise ForbiddenException(reason=message, body=body, error_body=error_body)
+                raise ForbiddenException(message=message, response_body=body, response_headers=headers, error_body=error_body)
             if code == 404:
-                raise NotFoundException(reason=message, body=body, error_body=error_body)
+                raise NotFoundException(message=message, response_body=body, response_headers=headers, error_body=error_body)
             if code == 409:
-                raise ConflictException(reason=message, body=body, error_body=error_body)
+                raise ConflictException(message=message, response_body=body, response_headers=headers, error_body=error_body)
             if code == 422:
-                raise UnprocessableEntityException(reason=message, body=body, error_body=error_body)
-            raise ClientException(status=code, reason=message, body=body, error_body=error_body)
+                raise UnprocessableEntityException(message=message, response_body=body, response_headers=headers, error_body=error_body)
+            raise ClientException(code=code, message=message, response_body=body, response_headers=headers, error_body=error_body)
         if code >= 500:
             if code == 500:
-                raise InternalServerErrorException(reason=message, body=body, error_body=error_body)
-            raise ServerException(status=code, reason=message, body=body, error_body=error_body)
-        raise ApiException(status=code, reason=message, body=body, error_body=error_body)
+                raise InternalServerErrorException(message=message, response_body=body, response_headers=headers, error_body=error_body)
+            raise ServerException(code=code, message=message, response_body=body, response_headers=headers, error_body=error_body)
+        raise ApiException(code=code, message=message, response_body=body, response_headers=headers, error_body=error_body)

src/main/resources/templates/python/exceptions.mustache

@@ -97,41 +97,40 @@ class ApiKeyError(OpenApiException, KeyError):
 class ApiException(OpenApiException):
     def __init__(
         self,
-        status: Optional[int] = None,
-        reason: Optional[str] = None,
+        code: Optional[int] = None,
+        message: Optional[str] = None,
         http_resp: Optional[Any] = None,
         *,
-        body: Optional[str] = None,
-        data: Optional[Any] = None,
+        response_body: Optional[str] = None,
+        response_headers: Optional[Any] = None,
         error_body: Optional[Any] = None,
     ) -> None:
-        self.status = status
-        self.reason = reason
-        self.body = body
-        self.data = data
-        self.headers: Optional[Any] = None
+        self.code = code
+        self.message = message
+        self.response_body = response_body
+        self.response_headers = response_headers
         self.error_body = error_body
 
         if http_resp:
-            if self.status is None:
-                self.status = http_resp.status
-            if self.reason is None:
-                self.reason = http_resp.reason
-            if self.body is None:
+            if self.code is None:
+                self.code = http_resp.status
+            if self.message is None:
+                self.message = http_resp.reason
+            if self.response_body is None:
                 try:
-                    self.body = http_resp.data.decode('utf-8')
+                    self.response_body = http_resp.data.decode('utf-8')
                 except Exception:
                     pass
-            self.headers = http_resp.getheaders()
+            self.response_headers = http_resp.getheaders()
 
     def __str__(self) -> str:
         """Custom error messages for exception"""
-        error_message = '({0})\nReason: {1}\n'.format(self.status, self.reason)
-        if self.headers:
-            error_message += 'HTTP response headers: {0}\n'.format(self.headers)
+        error_message = '({0})\nReason: {1}\n'.format(self.code, self.message)
+        if self.response_headers:
+            error_message += 'HTTP response headers: {0}\n'.format(self.response_headers)
 
-        if self.data or self.body:
-            error_message += 'HTTP response body: {0}\n'.format(self.data or self.body)
+        if self.response_body:
+            error_message += 'HTTP response body: {0}\n'.format(self.response_body)
 
         return error_message