From 56921e10d28f7a2917aae23090df89de21b8bae3 Mon Sep 17 00:00:00 2001
From: YueGuobin <yueguobin@outlook.com>
Date: Tue, 21 Apr 2026 12:46:48 +0800
Subject: [PATCH] docs: add API error response format documentation

Document unified error response format across all GNS3 API endpoints,
including HTTP status codes, error types, and client-side error handling
patterns.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 docs/README.md                       |  3 ++
 docs/features/api-error-responses.md | 80 ++++++++++++++++++++++++++++
 2 files changed, 83 insertions(+)
 create mode 100644 docs/features/api-error-responses.md

diff --git a/docs/README.md b/docs/README.md
index d21387d04..7b40b951c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -66,6 +66,9 @@ Aggregated server statistics API (`GET /v3/statistics`) for monitoring dashboard
 ### VNC WebSocket Console (`features/vnc-websocket-console.md`)
 Browser-based VNC console access via WebSocket. The Controller acts as WebSocket-to-WebSocket relay, and Compute bridges WebSocket to TCP for QEMU/Docker VMs. Supports noVNC clients.
 
+### API Error Responses (`features/api-error-responses.md`)
+Unified error response format across all GNS3 API endpoints. Documents HTTP status codes, error types, and client-side error handling patterns.
+
 ### Web Wireshark (`features/web-wireshark-business-process.md`)
 Web-based packet capture analysis using Docker + xpra HTML5 client. Zero-install Wireshark experience directly in the browser, integrated with GNS3 topologies.
 
diff --git a/docs/features/api-error-responses.md b/docs/features/api-error-responses.md
new file mode 100644
index 000000000..cbed7cddc
--- /dev/null
+++ b/docs/features/api-error-responses.md
@@ -0,0 +1,80 @@
+# API Error Response Format
+
+## Overview
+
+GNS3 Server uses a unified error response format across all API endpoints. All error responses return a JSON object with a `message` field containing the error details.
+
+## Response Format
+
+```json
+{
+  "message": "Error description here"
+}
+```
+
+## Error Types
+
+| Error Type | HTTP Status | Description |
+|------------|-------------|-------------|
+| `ControllerBadRequestError` | 400 | Invalid request parameters (e.g., validation failure) |
+| `ControllerUnauthorizedError` | 401 | Missing or invalid authentication |
+| `ControllerForbiddenError` | 403 | User lacks required privileges |
+| `ControllerNotFoundError` | 404 | Resource not found |
+| `ControllerError` | 409 | General conflict (e.g., duplicate name) |
+| `ControllerTimeoutError` | 408 | Operation timed out |
+| `ComputeConflictError` | 409 | Compute node returned a conflict |
+| `RequestValidationError` | 422 | Pydantic/FastAPI validation error (field missing or type mismatch) |
+| `SQLAlchemyError` | 500 | Database error |
+
+## Error Response Examples
+
+### Template Already Exists (409)
+```json
+{
+  "message": "A template with name 'my-template' already exists"
+}
+```
+
+### Validation Error (422)
+```json
+{
+  "message": "image field is required"
+}
+```
+
+### Permission Denied (403)
+```json
+{
+  "message": "Permission denied (privilege Template.Allocate is required)"
+}
+```
+
+### Invalid Template Type (400)
+```json
+{
+  "message": "JSON schema error received while creating new template: ..."
+}
+```
+
+## Client-Side Error Handling
+
+When handling errors in the GNS3 Web UI or API clients:
+
+```javascript
+// Extract error message from response
+function extractErrorMessage(error) {
+  if (error.error && error.error.message) {
+    return error.error.message;
+  }
+  if (error.message) {
+    return error.message;
+  }
+  return 'Unknown error';
+}
+```
+
+## References
+
+- Exception handlers: `gns3server/api/server.py`
+- Template validation: `gns3server/schemas/controller/templates/`
+- Error classes: `gns3server/controller/controller_error.py`