mirror of
https://github.com/GNS3/gns3-server.git
synced 2026-08-27 20:40:13 +03:00
56921e10d2
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>
81 lines
2.0 KiB
Markdown
81 lines
2.0 KiB
Markdown
# 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`
|