gns3-server/docs/features/api-error-responses.md

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

{
  "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)

{
  "message": "A template with name 'my-template' already exists"
}

Validation Error (422)

{
  "message": "image field is required"
}

Permission Denied (403)

{
  "message": "Permission denied (privilege Template.Allocate is required)"
}

Invalid Template Type (400)

{
  "message": "JSON schema error received while creating new template: ..."
}

Client-Side Error Handling

When handling errors in the GNS3 Web UI or API clients:

// 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