Add server error handler (#31)

Author: cubahno

AGENTS.md

@@ -253,6 +253,19 @@ Documentation is in `docs/` using MkDocs. Key files:
 2. Add to `nav:` section in `mkdocs.yml`
 3. For extensions, create in `docs/extensions/` and add under Extensions nav
 
+### Code snippets in docs
+Documentation uses MkDocs snippets to include code from example files. The format is:
+```
+--8<-- "path/to/file.go:start_line:end_line"
+```
+For example: `--8<-- "extensions/xgotype/gen.go:11:14"` includes lines 11-14 from that file.
+
+**After regenerating examples**, verify that line number references in docs are still correct:
+```bash
+grep -rn '\-\-8<\-\-' docs/ | grep -E ':[0-9]+:[0-9]+'
+```
+Then check each referenced file to ensure the line ranges still point to the expected code.
+
 ### Local preview
 ```bash
 pip install mkdocs-material

configuration-schema.json

@@ -268,6 +268,10 @@
           "type": "string",
           "description": "Package alias to prefix model types with. Used when models are generated separately (generate.models: false). Example: 'types' will generate 'types.User' instead of 'User'."
         },
+        "multipart-max-memory": {
+          "type": "integer",
+          "description": "Maximum memory in MB for multipart form parsing. Defaults to 32MB. Files exceeding this are stored in temp files."
+        },
         "validation": {
           "$ref": "#/definitions/HandlerValidation",
           "description": "Validation options for request/response validation in handlers."

docs/configuration.md

@@ -250,6 +250,18 @@ generate:
 
 This generates `types.User` instead of `User` in the handler code.
 
+#### `generate.handler.multipart-max-memory`
+**Type:** `integer` | **Default:** `32`
+
+Maximum memory in MB for multipart form parsing. Files exceeding this limit are stored in temporary files on disk.
+
+```yaml
+generate:
+  handler:
+    kind: chi
+    multipart-max-memory: 64
+```
+
 #### `generate.handler.validation.request`
 **Type:** `boolean` | **Default:** `false`
 
@@ -463,7 +475,50 @@ error-mapping:
   UpdateClientErrorResponseJSON: arrayField[].code
 ```
 
-When configured, the response type will have an `Error() string` method that returns the value from the specified field.
+When configured, the response type will have:
+
+1. **`Error() string` method** - Returns the value from the specified field path
+2. **Constructor function** - `NewTypeName(message string)` for easy error creation
+
+### Generated Code Example
+
+Given this configuration:
+
+```yaml
+error-mapping:
+  InvalidRequestError: error.message
+```
+
+The generator produces:
+
+```go
+type InvalidRequestError struct {
+    ErrorData *ErrorData `json:"error,omitempty"`
+}
+
+func (i InvalidRequestError) Error() string {
+    res0 := i.ErrorData
+    if res0 == nil {
+        return "unknown error"
+    }
+    return res0.Message
+}
+
+func NewInvalidRequestError(message string) InvalidRequestError {
+    return InvalidRequestError{ErrorData: &ErrorData{Message: message}}
+}
+```
+
+The constructor is useful in server implementations for returning typed errors:
+
+```go
+func (s *Service) CreateUser(ctx context.Context, opts *CreateUserOpts) (*CreateUserResponse, error) {
+    if opts.Body.Email == "" {
+        return nil, NewInvalidRequestError("email is required")
+    }
+    // ...
+}
+```
 
 See [examples/client/example1/cfg.yaml](https://github.com/doordash-oss/oapi-codegen-dd/blob/main/examples/client/example1/cfg.yaml){:target="_blank"} for a complete example.
 

docs/server-generation.md

@@ -370,6 +370,143 @@ func TestGetUser(t *testing.T) {
 }
 ```
 
+## Error Handling
+
+The generated code includes a flexible error handling system that separates error classification from error response formatting.
+
+### Error Types
+
+The `HTTPAdapter` handles four types of errors:
+
+| Error Kind | Description | Default Status |
+|------------|-------------|----------------|
+| `OapiErrorKindParse` | Parameter parsing errors (invalid path/query/header) | 400 |
+| `OapiErrorKindDecode` | Request body decoding errors (invalid JSON, form data) | 400 |
+| `OapiErrorKindValidation` | Request validation errors (failed schema validation) | 400 |
+| `OapiErrorKindService` | Service/business logic errors from your implementation | 500 (or typed) |
+
+### Default Behavior
+
+The `OapiDefaultErrorHandler` respects the `Accept` header:
+
+- **JSON** (`application/json`, `*/*`, or empty): Returns JSON response
+- **Other**: Returns plain text
+
+```go
+// JSON error response for parse/decode/validation errors
+{
+    "error": "invalid parameter \"id\": strconv.Atoi: parsing \"abc\": invalid syntax"
+}
+```
+
+Service errors are JSON-encoded directly, so the response structure matches your error type's JSON tags.
+
+### Custom Error Handler
+
+Implement the `OapiErrorHandler` interface to customize error responses, add logging, or collect metrics:
+
+```go
+type OapiErrorHandler interface {
+    HandleError(w http.ResponseWriter, r *http.Request, statusCode int, err error)
+}
+```
+
+The `err` parameter is either:
+
+- **`OapiHandlerError`** - A generic handler error (parse, decode, validation) with context fields
+- **Typed error** - An error type from your OpenAPI spec (when `error-mapping` is configured)
+
+```go
+type OapiHandlerError struct {
+    Kind          OapiErrorKind  // Type of error (Parse, Decode, Validation, Service)
+    OperationID   string         // OpenAPI operation ID (e.g., "GetUser", "CreateOrder")
+    Message       string         // Error message
+    ParamName     string         // Parameter name (for parse errors)
+    ParamLocation string         // Parameter location: "path", "query", "header" (for parse errors)
+}
+```
+
+Example custom handler with logging:
+
+```go
+type LoggingErrorHandler struct {
+    logger *slog.Logger
+}
+
+func (h *LoggingErrorHandler) HandleError(w http.ResponseWriter, r *http.Request, statusCode int, err error) {
+    // Check if it's a generic handler error
+    if handlerErr, ok := err.(api.OapiHandlerError); ok {
+        h.logger.Error("request error",
+            "operation", handlerErr.OperationID,
+            "kind", handlerErr.Kind,
+            "error", handlerErr.Message,
+            "status", statusCode,
+            "param", handlerErr.ParamName,
+            "param_location", handlerErr.ParamLocation,
+        )
+    } else {
+        // Typed error from OpenAPI spec or service error
+        h.logger.Error("service error",
+            "error", err.Error(),
+            "status", statusCode,
+        )
+    }
+
+    // Write response
+    w.Header().Set("Content-Type", "application/json")
+    w.WriteHeader(statusCode)
+
+    if handlerErr, ok := err.(api.OapiHandlerError); ok {
+        json.NewEncoder(w).Encode(map[string]string{
+            "error": handlerErr.Message,
+        })
+    } else {
+        // Typed error - encode directly to match API contract
+        json.NewEncoder(w).Encode(err)
+    }
+}
+```
+
+Use your custom handler with `WithErrorHandler`:
+
+```go
+svc := api.NewService()
+handler := api.NewRouter(svc,
+    api.WithErrorHandler(&LoggingErrorHandler{logger: slog.Default()}),
+)
+```
+
+### Typed Error Responses
+
+When your OpenAPI spec defines error response types and you configure `error-mapping`, the generator creates typed errors with constructors:
+
+```yaml
+# cfg.yaml
+error-mapping:
+  InvalidRequestError: error.message
+```
+
+This generates:
+
+```go
+func NewInvalidRequestError(message string) InvalidRequestError {
+    return InvalidRequestError{ErrorData: &ErrorData{Message: message}}
+}
+```
+
+Use in your service implementation:
+
+```go
+func (s *Service) CreateUser(ctx context.Context, opts *CreateUserOpts) (*CreateUserResponse, error) {
+    if opts.Body.Email == "" {
+        return nil, NewInvalidRequestError("email is required")
+    }
+    // ...
+}
+```
+
+The `HTTPAdapter` automatically detects typed errors and uses the appropriate status code from your OpenAPI spec.
+
 ## Examples
 
 Complete examples for each framework are available in the repository: